mirror of
https://github.com/CopilotKit/CopilotKit.git
synced 2026-09-14 16:26:20 +08:00
codex/cloudplot-showcase-migration
951 Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
 Jerel John Velarde
|
01009860f3 |
Merge remote-tracking branch 'origin/main' into codex/cloudplot-showcase-migration
# Conflicts: # pnpm-lock.yaml |
||
|
Jerel John Velarde
|
b9d9d700af | fix(showcases): protect CloudPlot production runtime | ||
|
Alem Tuzlak
|
1e9f104eb6 | chore(examples): allowlist Vite Vue Inspector build configs | ||
|
Ben Taylor
|
9e488f7a51 |
test(examples): gate the starters' Intelligence wiring block on one shape (closes OSS-982) (#6716)
**Merge order: #6711 → #6718 → this PR.** #6718 rewrites `identifyUser` in the same 22 blocks and is a sibling of this branch, not stacked on it, so the two overlap on the same lines. Landing the gate last means it ratchets on the finished shape and avoids a conflict. If this PR goes first instead, #6718 goes red until it moves all 22 sites together — which is the gate working, but noisier. Stacked on #6711 — merge that first. This branch descends from it, so the diff below carries its commit too; GitHub drops those once #6711 lands. Basing this PR on `main` rather than on #6711's branch is deliberate: 17 of 35 workflows filter `pull_request: branches: [main]`, including the one this PR extends, so a PR based on the 981 branch would not run the check it adds. ## Problem The marked block that wires managed Intelligence is the region a hosted reader copies verbatim, and nothing checked it. Both gaps are deliberate, not accidental: - `examples/integrations/_parity/manifest.json` lists `src/app/api/copilotkit/**` under `allowedDivergence` for every instance it tracks. What parity does hold byte-identical is the demo frontend: 54 verbatim paths of example canvas, todo columns and charts. - No `examples/integrations/*/docker-compose.test.yml` sets `COPILOTKIT_LICENSE_TOKEN`. The wiring is a ternary on that variable, so all 13 smoke-tested starters take the else arm. The `intelligence:` arm has never executed in CI, in any starter. The cost was already visible. The block's code was byte-identical in 21 of 22 starters, but its warning comment had drifted into five variants and the two `ms-agent-framework-*` starters shipped the `demo-user` stub with no warning at all. Comment drift is harmless by itself; it is the tracer showing nothing held the region still, and it is how the localhost default of #6711 survived in all 22 copies at once. ## Change `scripts/validate-intelligence-wiring-block.ts` greps the opening marker, compares every site against the north-star starter, and fails on the first line that differs. Two normalisations keep it usable: - The block is dedented, because `agentcore` nests it two levels deeper — its runtime is a Lambda handler, not a Next.js route. - The else arm's runner name is masked, because `agentcore` runs `AgentCoreRunner` in front of a Bedrock AgentCore session where an in-process runner has nothing to run. `EXPECTED_RUNNER` holds that one exception, so a runner swapped in by accident still fails. Everything else, comment text included, must match to the byte. Then the warning is unified at all 22 sites on the fullest existing wording, which also says the id must exist in Intelligence or thread operations can fail. It compares against the north star rather than a literal kept in the script, so improving the block means editing `langgraph-python` and running the other 21 to match. ## What it does and does not guarantee It is a shape gate, not a content gate: 22 identically wrong copies still pass. What it guarantees is that a fix reaches all of them or none. The check passes on day one — 21 of 22 already matched on code — so it is a ratchet, not a migration. ## Verification Mutating a real starter three ways, each caught: | Mutation | Reported as | | --- | --- | | Dropped one comment line | `line 15 differs from the north star`, exit 1 | | \`InMemoryAgentRunner\` → \`SomeOtherRunner\` | `else arm uses SomeOtherRunner; expected InMemoryAgentRunner` | | Reintroduced \`?? \"http://localhost:4201\"\` | `line 6 differs`, both sides shown | The third matters: the #6711 regression is now caught at a second site, independent of the env-name validator. Commands run, all exit 0: - `pnpm exec vitest run scripts/__tests__/validate-intelligence-wiring-block.test.ts scripts/__tests__/validate-intelligence-env-names.test.ts` — 30 passed - `pnpm check:intelligence-wiring-block` — `All 22 Intelligence wiring sites match langgraph-python.` - `pnpm check:intelligence-env-names` — unaffected, still canonical - `pnpm parity:verify` - `oxfmt --check`, `oxlint`, and `tsc --noEmit --strict` on the new pair Two tests guard the gate against going vacuous: one asserts at least 22 marker files are discovered, so an empty violation list cannot pass on an empty file list. Not run locally: the lefthook pre-commit suite, which fails environmentally in a worktree without per-package installs (`sh: vite: command not found`). This diff touches no package source. ## Not covered Enrolling the `intelligence:` arm in the smoke path. It needs a license token in CI secrets and an endpoint reachable from the compose network — a different size of job, tracked separately. |
||
|
Ben Taylor
|
4b73ce3c83 |
fix(examples): stop overriding the managed Intelligence URL defaults (closes OSS-981) (#6711)
## What does this PR do? `CopilotKitIntelligence` is built to be correct when the caller says nothing: omitting `apiUrl`/`wsUrl` resolves to `https://api.intelligence.copilotkit.ai` and `wss://realtime.intelligence.copilotkit.ai`, and its docstring says so outright — *"leaving both unset is always correct against it."* Every starter's runtime route defeated that default: ```ts apiUrl: process.env.INTELLIGENCE_API_URL ?? "http://localhost:4201", wsUrl: process.env.INTELLIGENCE_GATEWAY_WS_URL ?? "ws://localhost:4401", ``` With the variables unset — the correct configuration for a managed user — the `??` supplies localhost and the runtime aims at a local stack that is not running. This is the artifact `copilotkit init` clones, so it is the first thing a new managed user runs. The starter's own `.env.example` already warns about exactly this failure, two files away: > `INTELLIGENCE_API_URL` and `INTELLIGENCE_GATEWAY_WS_URL` point at a self-hosted or local Intelligence deployment only — leave them unset when using managed Intelligence, or the channel host and runtime will try to reach a local stack that usually is not running. So the documentation was right and the code contradicted it. `channel-host.mts`, in the same directories, already had the correct shape. ### The fix **22 runtime wiring sites** (20 route handlers, `adk-angular/server.ts`, and the AgentCore Lambda) now use the conditional spread these starters already use in `channel-host.mts`, so a self-hosted override still works and the managed default applies when absent: ```ts ...(process.env.INTELLIGENCE_API_URL ? { apiUrl: process.env.INTELLIGENCE_API_URL } : {}), ``` No hosted URL is written into the examples — the library already owns them, so this is a deletion. **3 `.env.example` files** (`agent-spec`, `llamaindex`, `mcp-apps`) set the same values *uncommented*. Two do it directly beneath a comment telling the reader to leave them unset, and an `.env.example` is copied to `.env`, so these were the remaining route to a localhost value once the code default was gone. Commented out to match the other nineteen starters; `agent-spec` had no explanation at all and gets the standard one. **A guard**, added to the existing `scripts/validate-intelligence-env-names.ts` rather than a new script — it already polices the canonical Intelligence key name and the two dead hosts, and its workflow is deliberately unfiltered so it sees every README, example and skill. Two rules: `managedUrlFallback` (a `??`/`||` default on either variable) and `managedUrlEnvFileAssignment` (an uncommented env-example assignment). The rule is the *pattern*, not the literal, so a staging host substituted for localhost fails the same way. Five files legitimately want a local target and are allowlisted with their reasons: the `playwright.config.ts` and `.env.example` of the banking and reskinnable-demo showcases (own vendored compose ports 7050/7053 and 7250/7253, own seeded org keys) and `agentcore/docker/.env.example` (the documented local development stack). Resolving those to the managed hosts would aim an offline test suite at production. `scripts/__tests__` has no general runner, so the workflow runs this test file explicitly, following the `plugin-skills-check.yml` precedent — otherwise a rule that silently stopped matching would leave the check passing on an empty result. ## Related PRs and Issues - Closes OSS-981. - Supersedes the canceled ENT-922, whose blocker ("do not invent hosted URLs; rewrite once the managed env contract is final") no longer applies: the contract shipped as `MANAGED_INTELLIGENCE_API_URL` / `MANAGED_INTELLIGENCE_WS_URL`, and the fix removes a fallback rather than adding a URL. - ENT-949 shipped a warning for this class of mistake, but `warnOnPartialHostOverride` only fires on a *partial* override — both values defaulting to localhost together is not partial, so nothing warned. ## Verification - `pnpm exec vitest run scripts/__tests__/validate-intelligence-env-names.test.ts` — 13 passed. Written first: the rules were red before they existed, then reported **48 violations across 24 files** for the code rule and **10 across 5** for the env-file rule; the fixes took both to green. - `pnpm check:intelligence-env-names` — exit 0. - `oxfmt --check` and `oxlint` over all 25 touched files — clean. - The spread typechecks under `strict` + `exactOptionalPropertyTypes`, the setting that would reject `apiUrl: string | undefined`. - The marked wiring block stays byte-identical across 21 of 22 starters (`agentcore` differs only in its runner), and no `localhost` remains inside any marked block. - Not run locally: the 13 starter Next builds. `test_smoke-starter.yml` typechecks the route handlers in CI on this PR. ### Out of scope `agentcore/docker/docker-compose.yml` keeps its `${INTELLIGENCE_API_URL:-http://localhost:4201}`: it is compose substitution in the documented local-dev stack, not shipped runtime code. Separately that default cannot work anyway — inside the bridge container `localhost` is the container's own loopback — but that is a different bug. ## Checklist - [x] I have read the [Contribution Guide](https://github.com/copilotkit/copilotkit/blob/master/CONTRIBUTING.md) - [x] If the PR changes or adds functionality, I have updated the relevant documentation - [x] "Allow edits by maintainers" is checked 🤖 Generated with [Claude Code](https://claude.com/claude-code) |
||
|
Benjamin Taylor
|
314f1ca55d |
fix(examples): stop overriding the managed Intelligence URL defaults (closes OSS-981)
CopilotKitIntelligence resolves apiUrl/wsUrl to the managed hosts when they are omitted, and its own docstring says leaving both unset is always correct against the managed service. Every starter's runtime route supplied `?? "http://localhost:4201"` instead, so a managed reader who copied the block got a runtime aimed at a local stack that is not running -- the failure the starter's own .env.example warns about two files away. Replace the fallbacks with the conditional spread these same starters already use in channel-host.mts, so a self-hosted override still works and the managed default applies when it is absent. Three .env.example files also set the values uncommented, two of them directly under a comment telling the reader to leave them unset; comment those out to match the other nineteen starters. Guard both shapes in validate-intelligence-env-names.ts, which already polices the canonical Intelligence key name and hosts and runs unfiltered on every PR. The rule is the pattern rather than the literal, so a staging host substituted for localhost fails the same way. Local e2e harnesses and demo stacks that genuinely target a local deployment are allowlisted with their reasons. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> |
||
|
Benjamin Taylor
|
84dd86f2ed |
test(examples): gate the starters' Intelligence wiring block on one shape (closes OSS-982)
The marked block that wires managed Intelligence is the region a hosted reader copies verbatim, and nothing checked it. Both gaps were deliberate: the parity manifest lists `src/app/api/copilotkit/**` under `allowedDivergence` for every instance it tracks, and no `docker-compose.test.yml` sets `COPILOTKIT_LICENSE_TOKEN`, so every smoke-tested starter takes the else arm and the `intelligence:` arm has never run in CI. The cost was already visible. The block's code was byte-identical in 21 of 22 starters, but its warning comment had drifted into five variants and the two `ms-agent-framework-*` starters shipped the `demo-user` stub with no warning at all. That drift is how the localhost default of OSS-981 survived in all 22 copies at once. Add `scripts/validate-intelligence-wiring-block.ts`, which greps the opening marker, compares every site against the north-star starter, and fails on the first line that differs. Two normalisations keep it usable: the block is dedented, because `agentcore` nests it deeper, and the else arm's runner name is masked, because `agentcore` runs `AgentCoreRunner` in front of a Bedrock session where an in-process runner has nothing to run. Everything else, comment text included, must match to the byte. Then unify the warning at all 22 sites on the fullest wording, which also says the id must exist in Intelligence or thread operations can fail. The check passes on day one, so it is a ratchet rather than a migration. It is a shape gate, not a content gate: 22 identically wrong copies still pass. What it guarantees is that a fix reaches all of them or none. Not covered: enrolling the `intelligence:` arm in the smoke path. That needs a license token in CI and a reachable endpoint from the compose network, and is tracked separately. |
||
|
Benjamin Taylor
|
8483f434f7 |
fix(examples): stop overriding the managed Intelligence URL defaults (closes OSS-981)
CopilotKitIntelligence resolves apiUrl/wsUrl to the managed hosts when they are omitted, and its own docstring says leaving both unset is always correct against the managed service. Every starter's runtime route supplied `?? "http://localhost:4201"` instead, so a managed reader who copied the block got a runtime aimed at a local stack that is not running -- the failure the starter's own .env.example warns about two files away. Replace the fallbacks with the conditional spread these same starters already use in channel-host.mts, so a self-hosted override still works and the managed default applies when it is absent. Three .env.example files also set the values uncommented, two of them directly under a comment telling the reader to leave them unset; comment those out to match the other nineteen starters. Guard both shapes in validate-intelligence-env-names.ts, which already polices the canonical Intelligence key name and hosts and runs unfiltered on every PR. The rule is the pattern rather than the literal, so a staging host substituted for localhost fails the same way. Local e2e harnesses and demo stacks that genuinely target a local deployment are allowlisted with their reasons. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> |
||
|
Maxim
|
e3dafff825 |
chore(examples): remove banking showcase in favor of reskinnable-demo
The banking showcase is superseded by `examples/showcases/reskinnable-demo`, which ships the same banking experience as one of its runtime-swappable skins (alongside airline) on top of a shared shell. Keeping both means maintaining two copies of the same demo, so banking is sunset here. Removes the app and the things that referenced it: - `pnpm-workspace.yaml` — drops the workspace entry. Also fixes the adjacent NOTE, which attributed the canary AG-UI pin to "banking's agent" when it is reskinnable-demo's own Python deep agent that needs it. - `pnpm-lock.yaml` — regenerated. Only the removed importer and the peer-suffix re-keying it caused; no dependency version changes. - `examples/README.md` — the banking row becomes a reskinnable-demo row, so the successor is listed and the showcase count is unchanged. - `showcase/shell-docs/.../faq.mdx` — the Banking Assistant link retargets to reskinnable-demo instead of 404ing. - `.github/config-allowlist.txt` — drops the deleted `next.config.mjs`. Not changed: `scripts/migrate-demos.sh` and `scripts/archive-demo-repos.sh` still name `examples/showcases/banking`. Those are the already-executed one-shot manifests for the repo consolidation; the path is a historical record there, not a live reference. reskinnable-demo's `.env.example` and `docker-compose.yml` likewise still explain their +200 port offset in terms of banking's stack — the offset stays real, and "was cloned from banking" stays true. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> |
||
|
renovate[bot]
|
bf44b367b8 | chore(deps): update github actions | ||
|
Mike Ryan
|
6b9aadf025 |
fix(runtime): stop emitting a require() statement in published .d.cts (#6644)
Fixes the part of OSS-899 that is hard to defend: every `.d.cts` file we
publish from `@copilotkit/runtime` starts with a `require()` call.
## The bug
A consumer whose only source file is `import { CopilotRuntime } from
"@copilotkit/runtime";`, compiled with `strict` and `skipLibCheck:
false`, gets **81 errors** on a bare install of 1.68.3. **71 of them are
`TS1036` "Statements are not allowed in ambient contexts"**, raised
inside our own shipped declarations.
Cause is in `packages/runtime/tsdown.config.ts`. The banner that
guarantees `reflect-metadata` loads before `type-graphql` was returned
as a **string**. tsdown's `resolveChunkAddon` routes an *object* return
by chunk kind (`js` / `dts` / `css`) but applies a *string* return to
**every** emitted chunk — declarations included. So all 87 published
`.d.cts` files began:
```ts
require("reflect-metadata");
import { CopilotRuntimeLogger, ... } from "./lib/logger.cjs";
```
A `require()` call is a statement, and a `.d.ts` is an ambient context.
One error per file.
Two reasons this went unnoticed for so long:
- Every scaffolder sets `skipLibCheck: true`. Verified in genuine `ng
new` and `create-next-app` output. A developer who scaffolds normally
never sees it.
- The `.d.mts` flavour got `import "reflect-metadata";`, which is a
legal side-effect import in a declaration file. **ESM-resolving
consumers saw zero `TS1036`.** Only CJS resolution is affected.
## The fix
Return an object so tsdown routes by chunk kind — JS keeps its
`reflect-metadata` prologue, declarations get nothing.
The `fileName.includes("_virtual/_rolldown/runtime")` condition is
dropped as well, and that is the more interesting half.
`resolveChunkAddon` reassigns its own closure variable on the first
call:
```js
if (typeof chunkAddon === "function") chunkAddon = chunkAddon({ format, fileName: chunk.fileName });
```
so a function banner is evaluated **once** and its result reused for
every later chunk. The old config's comment ("propagates to all output
files per format") described that as intended behaviour, but it was
really a condition deciding the banner for the entire build based on
whichever chunk happened to be emitted first. Keying on `format` alone —
fixed per build — is order-independent.
The object form is tsdown's declared API, not a workaround:
`ChunkAddonFunction` returns `ChunkAddonObject | string | undefined`
where `ChunkAddonObject` is `{ js?, css?, dts? }`. `tsc --noEmit
--strict` on `tsdown.config.ts` against tsdown's own types is clean —
worth stating because the config is in no tsconfig `include`, so nothing
else typechecks it.
## The guard
`scripts/validate-dts-ambient.ts` parses each built declaration with the
TypeScript compiler API and fails on any top-level node that is not a
declaration, import, or export. Wired as a `check-dts` nx target shaped
exactly like the existing `publint` / `attw` / `compat-check` targets
(`dependsOn: ["build"]`, `inputs` on `dist/**`), and folded into the
`check:packages` script that the `package-quality` CI job already runs.
That job already builds runtime for `publint`, so the added cost is one
177-file parse.
Only `@copilotkit/runtime` opts in, because it is the only offender.
Running the validator itself over the built declarations of all 32
packages: **87 of runtime's 177** bad on the published 1.68.3 artifact,
and **0** in every other package. Others can opt in with the same
one-line script.
## Testing
**1. Reproduce the reported defect on the published package.** Bare `npm
install @copilotkit/runtime@1.68.3 typescript`, `probe.ts` importing
only `CopilotRuntime`, tsconfig with `strict`, `skipLibCheck: false`,
`module`/`moduleResolution` `nodenext`:
```
$ npx tsc --noEmit ; echo exit=$?
exit=1
$ grep -oE 'error TS[0-9]+' tsc.out | sort | uniq -c | sort -rn
71 error TS1036
5 error TS2416
2 error TS7016
2 error TS2307
1 error TS2694
```
81 errors, matching the issue. All 71 `TS1036` are at line 1, column 1
of a `.d.cts`.
**2. Confirm the mechanism.** Every published declaration's first line,
before the fix:
```
-- *.d.cts -- total: 87
87 require("reflect-metadata");
-- *.d.mts -- total: 90
90 import "reflect-metadata";
```
**3. Same probe across every public subpath, before and after.** Built
`packages/runtime` at 1.68.3 with this change and swapped the result
into the probe's `node_modules`. `total` is all errors; `1036` is the
subset this PR addresses.
| subpath | CJS before | CJS after | ESM before | ESM after |
| --- | --- | --- | --- | --- |
| `@copilotkit/runtime` | 81 (71×1036) | **10** (0) | 10 (0) | 10 (0) |
| `/v2` | 32 (29×1036) | **3** (0) | 3 (0) | 3 (0) |
| `/langgraph` | 15 (4×1036) | **7** (0) | 7 (0) | 7 (0) |
| `/v2/express` | 21 (18×1036) | **3** (0) | 3 (0) | 3 (0) |
| `/v2/hono` | 21 (19×1036) | **2** (0) | 2 (0) | 2 (0) |
| `/v2/node` | 22 (20×1036) | **2** (0) | 2 (0) | 2 (0) |
Zero `TS1036` on every subpath in both module modes, and **after the fix
each subpath's CJS count equals its ESM count** — the CJS-only penalty
is gone and nothing else moved. Every ESM column is untouched, which is
the expected result since `.d.mts` never carried the bad banner.
The errors that remain are the separate items catalogued on OSS-899
(optional-peer SDK types, `@types/cors`, a `lru-cache` variance error
from `graphql-yoga`, a zod namespace skew in
`@copilotkit/license-verifier`) and are not touched here.
**4. `reflect-metadata` still runs first in every JS output.** This is
what the banner exists for, so it is the thing most at risk from the
change:
```
cjs files with require("reflect-metadata") as line 1: 131 / total 131
mjs files with import "reflect-metadata" as line 1: 132 / total 132
```
**5. Nothing but the banner line changed.** Diffed every one of the 87
built `.d.cts` files against the published 1.68.3 artifact from line 2
onward. Exactly one file differs, and it is unrelated source drift — a
JSDoc env-var rename from `6f58b2c6a4` (`COPILOTKIT_API_KEY` →
`INTELLIGENCE_API_KEY`, refs OSS-881) that landed on main after 1.68.3
shipped. Line counts are also identical, so declaration sourcemaps do
not shift.
The `_virtual/_rolldown` reference count in declarations is 2 before and
2 after — that item is deliberately out of scope here.
**6. The guard catches the regression it exists for.** Reverted the
banner to its pre-fix string form, rebuilt, and ran the new target:
```
$ pnpm exec tsx ../../scripts/validate-dts-ambient.ts dist
Found 87 statement(s) in published declarations.
A .d.ts is an ambient context: only declarations, imports, and exports are
allowed. Each of these is a TS1036 error for consumers on skipLibCheck: false.
dist/agent/converters/aisdk.d.cts:1 require("reflect-metadata");
...
exit=1
```
Restored the fix and rebuilt:
```
$ pnpm exec tsx ../../scripts/validate-dts-ambient.ts dist
validate-dts-ambient: dist clean (177 files).
exit=0
```
**7. Validator unit tests, mutation-checked.**
`scripts/__tests__/validate-dts-ambient.test.ts`, 7 tests covering the
exact OSS-899 banner, the legal ESM form, every declaration form a real
`.d.ts` uses, line-number reporting, and ignoring sibling `.cjs`/`.map`
files.
```
Test Files 1 passed (1)
Tests 7 passed (7)
```
Then broke the mechanism three ways to confirm the tests are not
self-fulfilling:
| mutation | result |
|---|---|
| allow `ExpressionStatement` in the kind allowlist | 2 failed / 5
passed |
| drop the `line + 1` conversion | 2 failed / 5 passed |
| scan only `.d.ts`, not `.d.mts` / `.d.cts` | 3 failed / 4 passed |
| restored | 7 passed |
**8. Runtime suite and packaging targets, on a clean `pnpm install
--frozen-lockfile` in this worktree.**
```
$ nx run @copilotkit/runtime:test
Test Files 143 passed (143)
Tests 2073 passed (2073)
$ nx run-many -t publint,attw,check-dts --projects=@copilotkit/runtime
NX Successfully ran targets publint, attw, check-dts for project @copilotkit/runtime
```
`attw --profile node16` reports 🟢 from both CJS and ESM; the `node10`
failure is pre-existing and ignored by the profile.
**9. Formatting and types.** `oxfmt --check` clean on all three source
files; `tsc --noEmit --strict` clean on the new script.
## Overlap with #6476
#6476 (`adopt TypeScript 7 and tsdown 0.22`) bumps tsdown to 0.22.14 but
does **not** touch `packages/runtime/tsdown.config.ts`, so it does not
fix this. The two PRs conflict only textually — both add lines to
runtime's `scripts` block and to the root `package.json`. This fix uses
tsdown's documented object-banner form, so it holds whether or not 0.22
changed `resolveChunkAddon`'s memoization.
No changeset: this ships through the normal release scopes.
|
||
|
Tyler Slaton
|
7bff49739e | fix(runtime): replace retired Anthropic model IDs (#6616) | ||
|
Benjamin Taylor
|
8951232a0f |
fix(runtime): stop emitting a require() statement in published .d.cts
A consumer who imports @copilotkit/runtime and compiles with strict +
skipLibCheck: false gets 81 errors from our published declarations, 71 of
them TS1036 "Statements are not allowed in ambient contexts". Cause: the
tsdown banner that guarantees reflect-metadata loads before type-graphql
was returned as a string, and tsdown applies a string banner to every
emitted chunk -- declarations included. So all 87 published .d.cts files
began with `require("reflect-metadata");`, which is a statement and
illegal in an ambient context.
Returning an object instead lets tsdown route the banner by chunk kind, so
JS keeps its reflect-metadata prologue and declarations get nothing. The
fileName condition is gone too: tsdown's resolveChunkAddon reassigns its
own closure variable on the first call, so a function banner is evaluated
once and reused, meaning that condition was really deciding the banner for
the entire build from whichever chunk was emitted first. Keying on format
alone is order-independent.
This was invisible to us because every scaffolder sets skipLibCheck: true,
and because .d.mts got the legal `import "reflect-metadata";` form -- ESM
consumers never saw a single TS1036.
Adds a check-dts target that parses the built declarations and fails on any
top-level statement, wired into the existing package-quality job so the
class cannot come back silently.
Refs OSS-899
|
||
|
Mark
|
fc14045c0a | fix(showcase): register CrewAI flows production instance | ||
|
Tyler Slaton
|
0ae1e188a8 | ci: reject retired Anthropic model references | ||
|
Mark
|
0298616223 |
docs: add Claude Managed Agents cookbook (#6430)
## Summary - add an independently runnable Claude Managed Agents finance-assistant example - add a cookbook recipe that explains the CopilotKit runtime, managed-session mapping, and tool rendering flow - add the recipe to cookbook navigation, the overview grid, sidebar icon mapping, and render coverage - use the real Claude vector mark for the cookbook instead of the text-placeholder SDK asset - register the example's Vite configuration and managed-agent model with the repository CI allowlists - include a compact architecture diagram and links to the relevant rendering and CopilotKit Intelligence documentation - disable Claude's complete built-in toolset and expose only the scoped `show_growth_projection` runtime tool - make the provisioning model configurable through `ANTHROPIC_MODEL`, defaulting to `claude-fable-5` - bound CopilotKit request bodies to 256 KB and managed-agent turns to 90 seconds, while relying on the adapter's per-thread serialization - cap public run traffic at 20 provider-like attempts per client IP per minute and 2,000 successful starts per process per 24-hour window - restrict browser runtime requests with an exact Origin allowlist that supports same-origin or separately hosted frontends, and restrict iframe parents with CSP `frame-ancestors` - validate persisted managed-agent IDs at startup so malformed local configuration fails immediately - publish the interactive example on Railway and embed the live deployment in the cookbook - align the demo with the existing cookbook chat styling and show the `Project monthly investing` starter on first load ## Demo  ## Why This gives developers a focused example of connecting CopilotKit to Anthropic Claude Managed Agents without the extra surface area of a larger analyst application. The recipe follows the existing cookbook structure and keeps the live demo compact enough for the standard cookbook pane. Its managed environment has no outbound network or package-manager access, and its agent cannot use bash, filesystem, search, or fetch tools. The request, turn, per-IP, and process-wide limits bound public demo traffic without adding authentication or user friction. The traffic counters are intentionally in memory, reset on process restart, and are not shared across replicas, so the dedicated Anthropic workspace spend limit remains the durable cost backstop. The exact-Origin browser check reduces drive-by use but is explicitly documented as a control rather than authentication. The model override allows operators to select a lower-cost supported model during provisioning without editing source code. ## Validation - scoped formatting: passed - scoped lint: 0 warnings, 0 errors - shell-docs typecheck: passed - standalone example typecheck: passed - docs render tests: 26/26 passed - standalone example tests: 23/23 passed - shell-docs tests: 375/375 passed - shell-docs production build: passed (222/222 pages) - standalone example production build: passed - standalone npm lockfile validation: passed - build-config allowlist validator: passed - docs model-name validator: passed - exact-Origin regression coverage for run requests plus headerless same-origin runtime discovery: passed - malformed persisted agent-ID regression coverage: passed - live Railway root and iframe CSP: passed - live Railway runtime discovery, exact welcome copy, and first-load starter pill: passed - live three-turn AG-UI managed-agent run with `show_growth_projection`: passed - cookbook verified in the browser at desktop and narrow widths with no console errors or horizontal overflow |
||
|
Mike Ryan
|
b8b19834a2 |
fix(runtime): unify the Intelligence key name and publish the wiring (refs OSS-881) (#6595)
## What does this PR do? Closes the naming and documentation half of [OSS-881](https://linear.app/copilotkit/issue/OSS-881). Paired with CopilotKit/Intelligence#890, which adds `copilotkit verify` and tightens the evaluation rubric. ### 1. One name for the Intelligence key **Three** names for one value were live in CopilotKit's own documentation, and following the wrong one with a CLI-provisioned project yields an undefined key: | Name | Where | Code readers | | --- | --- | --- | | `INTELLIGENCE_API_KEY` | what `copilotkit project select` writes; all 34 integration examples; the docs site | 34 | | `COPILOTKIT_INTELLIGENCE_API_KEY` | 7 Channels package READMEs + packaged skills | **0** | | `COPILOTKIT_API_KEY` | `examples/slack`, `examples/teams`, and the TSDoc on `CopilotKitIntelligence` itself | 2 | `INTELLIGENCE_API_KEY` wins — it is the name the CLI provisions, and changing it would break every scaffolded project in the wild. - `COPILOTKIT_INTELLIGENCE_API_KEY` is **retired outright**. Nothing ever read it, so there is nothing to keep compatible. - `COPILOTKIT_API_KEY` stays **readable as a deprecated alias** in the two examples that consume it, so an existing `.env` keeps working, and is documented as deprecated everywhere it appears. The third name was the worst placed: it was in the TSDoc on `CopilotKitIntelligence`, which is what an IDE shows on hover. This was not only untidy. The CLI's own `channels-preflight` accepts `INTELLIGENCE_API_KEY` or `COPILOTKIT_API_KEY` — **not** `COPILOTKIT_INTELLIGENCE_API_KEY`, the name the Channels READMEs told people to set. So following a Channels README verbatim made `copilotkit channels` warn that no runtime API key was present while the key sat visibly in `.env`. After this PR the documented name is one preflight accepts. > [!NOTE] > `NEXT_PUBLIC_COPILOTKIT_API_KEY` is a **different value** — the legacy Copilot Cloud public key — and is deliberately left alone. ### 2. A real defect, not just naming skew `skills/runtime/references/intelligence-mode.md` documented `organizationId` as a `CopilotKitIntelligence` option, sourced from two further env names (`COPILOTKIT_INTELLIGENCE_ORG_ID`, `COPILOTKIT_ORG_ID`). `CopilotKitIntelligenceConfig` has no such field — the copy-pasteable sample it appeared in **would not compile**. Removed from the samples, and the prose telling readers to fetch a value for it corrected. That file is the only place those two names ever existed, which is very likely why the failing validation run reported that "the runtime reads `COPILOTKIT_INTELLIGENCE_API_KEY` and `COPILOTKIT_INTELLIGENCE_ORG_ID`". ### 3. Publish the Intelligence wiring The wiring instructions existed only inside `node_modules/@copilotkit/runtime/skills/`, and the only docs pages mentioning `CopilotKitIntelligence` at all were the two Channels frontends — so a developer on the plain web path had no page to reach it from. Adds **`/premium/connect-your-runtime`**: the wiring itself, how to confirm the credential is actually consumed, the self-hosted both-URLs-or-neither rule, and a troubleshooting table. Linked into both navs, and the skills reference now points at the published page. ### 4. A guard so it cannot drift back `scripts/validate-intelligence-env-names.ts` (`pnpm check:intelligence-env-names`), wired to lefthook and a new workflow. The workflow is **intentionally unfiltered**. The two workflows that would otherwise cover this both filter: `plugin-skills-check` by `paths:`, and `static/quality` by `paths-ignore: examples/**` — which is exactly where the deprecated alias lives. Scoping the job would re-open the hole it exists to close. Legitimate alias sites live in `ALIAS_ALLOWLIST`. ## Related PRs and Issues - [OSS-881](https://linear.app/copilotkit/issue/OSS-881) — needs **both** PRs; neither closes it alone - CopilotKit/Intelligence#890 — items 1 and 4 (`copilotkit verify` + rubric contract 1.3.0) ## Verification - Full lefthook pre-commit ran green: `check-plugin-skills`, `lint-fix`, the new `check-intelligence-env-names`, and `test`/`publint`/`attw` across **25 projects**. - `examples/slack` `managed.test.ts` extended to cover **both** the canonical name and the alias fallback, and proven non-vacuous — removing the fallback turns the new test red. - The drift guard proven non-vacuous the same way: reintroducing a retired name fails it, exit 1. - `oxfmt` and `oxlint` clean on every file touched (0 errors). ## Checklist - [x] I have read the [Contribution Guide](https://github.com/copilotkit/copilotkit/blob/master/CONTRIBUTING.md) - [x] If the PR changes or adds functionality, I have updated the relevant documentation 🤖 Generated with [Claude Code](https://claude.com/claude-code) |
||
|
Mark
|
d50e8d7e7c | Merge branch 'main' into codex/claude-managed-agents-cookbook | ||
|
David McKay
|
35ea9eee36 |
feat(reskinnable-demo): run banking on a nested LangChain deep agent with a streaming CLI console (#6581)
Replaces the Codex CLI harness with **LangChain deep agents (Python)**:
sandboxed shell execution, parallel research subagents, no external
harness binary, our own API key.
All ten beats have been walked in a browser, and the demo now has its
own CI job. **Ready for review.**
## What banking's agent is now
```
banking gpt-5.4, temp 0
│ banking's own prompt · the browser's frontend tools · Intelligence
│ memory tools · render_report for the canvas
└─ expense-analyst gpt-5.6-sol, reasoning_effort=high
│ sandboxed shell (LocalShellBackend) · submit_expense_report
└─ merchant-researcher gpt-5.4, one per merchant
search_merchant (Tavily)
```
Six skins still run in-process as `BuiltInAgent`s. `banking` is an
`HttpAgent` pointed at `agent/`.
Each level exists because something about it must differ from its parent
— prompt, model, reasoning effort, tool set. A single agent had nowhere
to put any of that.
### Why the whole agent moved, not just the expense beat
The obvious design was a second agent id for the long-running beat,
leaving banking's `BuiltInAgent` alone. That was built first, and it
does not survive the requirement *"start the analysis, switch threads,
run other pills, come back to it."*
**Threads are scoped per agent.** `listThreads` takes `agentId` as a
required parameter, and measured against the running app the two lists
were disjoint — `banking` 46 threads, `banking-expenses` 10. The v2
runtime has no handoff mechanism, and `defineTool`'s `execute` takes
`(args)` with no emitter, so a tool cannot stream a multi-minute run
into the conversation. One conversation list means one agent.
### Why the beat is a subagent rather than prose in one prompt
It started as a section appended to banking's prompt. That left per-beat
configuration homeless (model, effort and recursion limit are all
agent-level, and there was one agent), and made banking's
~21,000-character rulebook ride every one of the ~20 model calls the run
makes — re-sending rules about markdown tables while the agent read a
CSV.
Reached as a `CompiledSubAgent`, because a raw `SubAgent` spec has no
`subagents` field and this one needs its own: the per-merchant fan-out
is a headline of the beat, and a flat subagent could only research
serially. A probe confirmed nesting survives — the analyst's `task`
dispatches, the researchers' `search_merchant` calls and the final
report tool all reach `astream_events`.
## The console
One CLI window in the transcript carries the whole run: narration, `$
execute`, `search "…"`, `→ merchant-researcher: …`, results, indented by
depth so a ten-way fan-out reads as a fan-out. Subagent narration is
suppressed from the conversation so the console is the single place the
harness is visible; banking's own replies still render normally.
`shell/subagents/subagent-activity.tsx` subscribes to the agent's
**event stream**. Reading `agent.messages` — the first design — was
wrong twice: messages materialise at the `MESSAGES_SNAPSHOT` (two per
run), so the pane sat still for minutes then filled at once; and
persisted messages carry no `subagentRunId`, so the harness's narration
could not be told from banking's reply. The fold is pure and idempotent,
so the same code serves the live subscription and a replay of the
thread's stored events when a conversation is reopened.
Three heuristics were deleted along the way, each replaced by identity
the protocol already carried:
| heuristic | replaced by |
|---|---|
| console anchored on "the first tool call" | the run's first `task`
call, from **message order** (durable; the event-derived version
rendered one console *per delegation* on a restored thread — six,
measured) |
| `CONSOLE_TOOL_NAMES` allowlist | presence of `subagentRunId` |
| `disable_streaming` on the researchers | the canary's per-lane state |
The message filter suppresses **prose** and keeps **tool calls**: an
agent routinely narrates and calls a tool in one message, and returning
`null` for the whole message hid the report card — the run looked
perfect and ended with nothing to show.
## Canary stack, contained to this app
The subagent surface only exists on the canary line, and a released
`@ag-ui/client` ≤ 0.0.57 rejects `SUBAGENT_*` events **in the HTTP
transport before any middleware runs**, killing the stream. So the demo
leaves the root pnpm workspace and ships its own lockfile:
- `@copilotkit/* 1.68.3-canary.1786716392`
- `@ag-ui/* 0.0.59-canary.1786716392.0`
- `ag-ui-langgraph 0.0.43.dev1786716392` → `ag-ui-protocol
0.1.20.dev1786716392`
That keeps an unreleased protocol out of every other package in the
monorepo.
A 1.62.2-based canary was tried first and **could not compile the app**:
`workspace:*` is not a version, so the demo had no recorded lower bound
on the CopilotKit API it needs, and pointing it at 1.62.2 silently
rewound that API five minors. `OpenGenerativeUIActivityRenderer` — a
public `/v2` export since ~1.63 — was the first thing to break, and
there was no reason to think it was the only one. Rebasing the canary on
1.68.3 collapsed that whole class of risk.
## Verified against the running app
Every row is a measurement, not a claim.
| | |
|---|---|
| Registry shape | `/info`: `banking` = HttpAgent, other six =
BuiltInAgent |
| Sandboxed execution | 8 `execute` calls; agent writes and runs its own
Python |
| Parallel subagents | 6 `SUBAGENT_STARTED`/`FINISHED` pairs, 10
`search_merchant` |
| Canvas beat | `render_report` → a2ui middleware emits `activityType:
a2ui-surface` |
| Frontend tools | given two, picks `showTransactions`, emits no result,
emits **no prose** — the prompt's restraint rule surviving the port |
| Memory (Intelligence) | run is handed `recall_memory`, `save_memory`,
`forget_memory`, `knowledge_base_shell` |
| HITL round-trip | tool call out, answer back in, agent continues |
| Durable background run | client disconnected at 8s; run finished
unattended; thread replayed |
| Thread restore | 61 messages persisted incl. the report tool (an
earlier flat-subagent attempt collapsed to 4) |
| Report correctness | 14 rows, 9 researched, 6 filed with ids read out
of real 201 bodies, totals reconciling against their own rows |
| Run duration | 86s reported vs 98s wall clock |
## Correctness bugs found by running it
Each produced a confident, complete-looking wrong answer rather than an
error — the characteristic failure of a multi-minute agentic beat.
- **Beat 3d was dead, and it took the whole thread with it.** The bet
against this one was right. `ag_ui_langgraph` routes *every* attachment
to the model as an `image_url` block, documents included, so the Q2
invoice was rejected before the first token: `400 Invalid MIME type.
Only image types are supported`. The exception is raised inside the
model node, which kills the SSE stream — the runtime sees `RUN_ERROR:
terminated` with no cause and the browser renders **nothing**: no error
bubble, no failed message. And the crashed run is still checkpointed, so
every later message on that thread replays the rejected content and dies
the same way. One click on the pill killed the conversation permanently;
only restarting the service cleared it. Fixed here by a
`wrap_model_call` middleware that rewrites those blocks into LangChain
standard `file` blocks, and upstream in
[ag-ui#2476](https://github.com/ag-ui-protocol/ag-ui/pull/2476) (both
adapters, plus the return leg so a non-image attachment survives
`MESSAGES_SNAPSHOT`). The middleware is a stopgap with its deletion
condition written into its header — this service installs the adapter
from PyPI, so the upstream fix cannot reach it until published.
- **Totals did not match their own rows.** Every per-row amount matched
the CSV while the headline totals came back $1.00 and $0.20 high: the
model authored them instead of adding them. The card prints the total
directly above the rows it is the sum of. Fixed structurally — derived
in `submit_expense_report`, removed as parameters.
- **`amount` arrived as a string** on all 14 rows, silently defeating
`toLocaleString(…currency…)` so it printed `842.10` with no currency.
- **`merchantKind` non-answers.** With no search tool the model wrote a
bare `"unclear"`; with Tavily live it hedges in prose (`"unknown (likely
bookbindery/bookshop retail, but not established for this exact
merchant)"`), which an exact-match filter passed into a 60-character
label glued to the merchant name. Now rejected on leading token, hedging
language, and a 40-character cap.
- **The run clock reported 333s for a two-minute run.** It took the
oldest open stamp across the process because the tool could not name its
own run; model calls *after* the report re-stamped it and the leftover
became the next run's start. Now keyed per run via an injected
`ToolRuntime`.
- **`graph.with_config({"recursion_limit"})` is silently dropped** by
the AG-UI adapter. The agent completed the entire analysis, streamed
every argument of the final report, then died at LangGraph's default of
25 supersteps.
- **A sync `wrap_model_call` under `astream`** surfaces as a bare
`RUN_ERROR: terminated`, cause only in the service log.
- **`emit_raw_events` defaults to `True`**, piggybacking LangChain's
internal events onto the stream: 27,950,261 bytes → 374,086 with it off,
identical report. Matters because the thread *persists* those events for
replay.
- **`gpt-5.6-sol` + `reasoning_effort` + function tools 400s** on
`/v1/chat/completions`; needs `use_responses_api=True`. The first model
probe missed it by binding no tools — a model probe for an agent has to
bind one.
## Upstream findings (reported separately, not fixed here)
1. **`@copilotkit/runtime` drops `subagentRunId` when persisting
messages.** 2888 of 3026 stream events carry it; 0 of 53 persisted
messages do. Reproduced with Intelligence removed entirely, so it is the
runtime's message shape rather than the platform store — and
`@copilotkit/runtime`'s dist contains no occurrence of the field, while
`@ag-ui/core`, `ag-ui-protocol` and `@copilotkit/core` all model it. One
field threaded through would let the console rebuild from message
history and delete the event-replay seeding here.
2. **`copilotkit` 0.1.95 × `ag-ui-langgraph` 0.0.43** — the FastAPI
endpoint calls `agent.clone()` per request; 0.0.43's base `clone()`
hard-passes three kwargs the SDK subclass does not accept, so **every
request 500s**. Verified with a minimal repro on stock classes and by
reading published wheels (0.0.41/0.0.42 are fine — the window is 0.0.43
only). `sdk-python` requires `>=0.0.42` unbounded, so fresh installs
break, and `examples/showcases/deep-agents{,-finance-erp,-job-search}`
are one `uv lock --upgrade` away. Now open as #6592 (`**kwargs`
passthrough + 9 regression tests incl. a forward-compat guard); it needs
a `0.1.96` bump to reach PyPI before `main.py`'s
`BankingAGUIAgent.clone()` workaround can go — and note `agent/uv.lock`
pins `copilotkit 0.1.95`, so removing the workaround is a re-lock as
well as a delete. That branch also fixes 4 pre-existing failures in the
sdk-python suite from the same root cause — **`test_unit-python-sdk` may
currently be red on `main`; worth checking independently.**
3. **Both LangGraph AG-UI adapters send non-image attachments as
`image_url`**, so a PDF, audio clip or video is rejected on the block
kind — see beat 3d in *Correctness bugs*. Fixed in
[ag-ui#2476](https://github.com/ag-ui-protocol/ag-ui/pull/2476); carried
here as a middleware until that publishes.
Also verified and **not** a problem: pnpm 10.33.4 still applies
`package.json` `pnpm.overrides` despite warning that it ignores them —
the ~70 root overrides including the security pins are live, nothing was
silently unpinned. (Migration to `pnpm-workspace.yaml` is worth doing
anyway, since the installed pnpm is 11.21.0 where the field genuinely is
dropped; branch exists, byte-identical lockfile.)
## What is not done
1. **Docs are stale.** `CLAUDE.md` still says `AgentRegistration` is `{
createAgent: () => BuiltInAgent }` and that the route "builds one
`BuiltInAgent` per registered skin"; the reskin skill says the same in
three places, and `templates.md` scaffolds it. The real type is `() =>
AbstractAgent`. This app has a standing rule that every change answers
whether the skill went stale. It did — the skill's launcher step is
fixed, the `BuiltInAgent` claims are not.
3. **Pre-release dependencies**, now on both halves: the JS canaries in
this app's own `pnpm-lock.yaml`, and `ag-ui-langgraph` /
`ag-ui-protocol` pinned `==` to the matching `.dev` canaries in
`agent/pyproject.toml`. Both move to stable when the subagent work
ships.
4. `pnpm test:e2e` has not been run.
### Closed since this PR was opened
- **The demo has its own CI job** —
`.github/workflows/test_reskinnable-demo.yml`. Nx discovers projects
*through* the pnpm workspace (no `workspaceLayout` in `nx.json`), so
leaving it also left the repo-wide `nx run-many -t build`
(`static_compat.yml`), `-t check-types` (`static_quality.yml`) and `-t
test` (`test_unit.yml`) sweeps, and both static workflows carry
`paths-ignore: ["examples/**"]` besides. One job runs the four gates
(lint, typecheck, 2460 unit tests, build); a second syncs
`agent/uv.lock` with `--frozen` and asserts the subagent *capability*
rather than a version string, so it keeps meaning something after the
pin moves.
The build gate is the one a developer can least run locally: `next
build` corrupts a concurrently running dev server's PostCSS/Turbopack
cache — measured, `globals.css` transforms to garbage, every route 500s,
and a dev-server restart does not clear it because the corruption is on
disk.
**Its first two runs failed, both usefully**, and both bugs were
pre-existing:
1. `pnpm/action-setup@v6.0.10` with `package_json_file:` pointed at this
app still installed the **root's** pnpm 10.33.4 rather than this app's
pinned 10.10.0 — the resolver that ignores `pnpm.overrides`, which is
the only place three of the five `@ag-ui/*` canaries are pinned. Caught
only because the job asserts `pnpm --version` against the pin; it would
otherwise have installed under the wrong resolver and stayed green. Now
activated through corepack, which reads the nearest `package.json`.
2. `pnpm install` in this directory **never installed this app**. pnpm
walks *up* for a workspace root, found the repo's, and installed all 70
monorepo projects (4645 packages) while leaving this directory with no
`node_modules` — the next command failing as `sh: 1: eslint: not found`.
So the app that ships its own lockfile was uninstallable by its own
documented instruction. Fixed by giving it its own
`pnpm-workspace.yaml`; `ignore-workspace=true` in an `.npmrc` does
**not** work (CLI-only in pnpm 10.10, measured).
- **The canary `overrides` now live in `pnpm-workspace.yaml`**, their
supported home, as a side effect of that fix. They no longer depend on
`packageManager: pnpm@10.10.0` being the version that still reads
`package.json` — which matters because `@ag-ui/core`, `@ag-ui/encoder`
and `@ag-ui/proto` are pinned nowhere else and a released `@ag-ui/core`
rejects `SUBAGENT_*` in the HTTP transport.
- **All ten beats walked in a browser**, including 3d — which was
broken, for the reason in *Correctness bugs* above.
- **`./run-demo.sh` starts a complete demo.** It now brings up the
Python agent between the compose wait and `pnpm dev`, guarded on
`/health` so a re-run reuses a live one, and dies with `(cd agent && uv
sync)` when the venv is missing. `./stop-demo.sh` had the mirror gap and
now stops it too — that one mattered more than it looks: the start
script *reuses* a live :8124, so an orphan surviving teardown is
silently adopted by the next cold start, serving whatever code it was
launched with.
- **The agent's Python deps are pinned and locked.** They were not, and
the JS half was — so a colleague's fresh `uv sync` resolved the
*release* `ag-ui-langgraph 0.0.43`, which does not accept
`emit_subagent_events` and ships no subagent symbols. That is this PR's
headline feature, and it would have failed silently: `main.py` sets the
flag as an attribute, so the assignment succeeds against an object
nobody reads and the service starts clean. Now `==` pins plus a
committed `agent/uv.lock`, verified by building a venv from only the
tracked files and replaying a captured Q2-with-PDF payload through it.
- **The README told people to install from the repo root** "as a
workspace package". It is deliberately not one, so a root install did
nothing for this app — and installing in the right place did nothing
either, until the `pnpm-workspace.yaml` above.
## Relationship to #6501
Based on `b94e4bfb5d`, the last commit before Codex appears, which is
**not on `main`**. So this PR carries **9 commits: the 4 here plus the 5
foundation commits it shares with #6501** — harness types + fixture,
prompt/workspace, the OFFSITE-to-fixture invariant guard, the
summary-shape/filing-contract fix, and `POST /transactions`. Whichever
merges first shrinks the other. #6501 and #6565 are deliberately
untouched.
## A demo-design question, not a bug
The fixture's merchant names are invented, so `Cardinal & Ash` — the
prompt's own worked example of *"could be a restaurant or a law firm,
find out"* — cannot be resolved by real web search and stays `unclear`
alongside `Bluebonnet Provisions`. The beat's headline claim is that the
agent researches every merchant; real merchant names in the CSV would
make that land harder.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
https://claude.ai/code/session_01JRubZT6AS6LCGkcE2KzcfA
|
||
|
Maxim
|
80e83c8186 |
ci(reskinnable-demo): activate the app's pnpm via corepack, key the import smoke
First run (32398188492) failed twice, both usefully:
* `pnpm/action-setup@v6.0.10` with `package_json_file:` pointed at this
app still installed the ROOT's pnpm 10.33.4 rather than the app's pinned
10.10.0, and it cannot take a `version:` alongside a `packageManager`
field. The version assertion caught it instead of the job silently
installing under a resolver that ignores the three override-only
`@ag-ui/*` canary pins. corepack reads the nearest package.json, so it
resolves the app's pin and honours its +sha512 hash. The pnpm store is
now cached explicitly, keyed on this app's lockfile, since setup-node's
implicit pnpm cache needs pnpm installed before it runs.
* The import smoke needs OPENAI_API_KEY. `main.py` calls `build_agent()`
at import time and that raises without it. A placeholder is enough —
constructing a ChatOpenAI does not validate the key or touch the network.
|
||
|
Maxim
|
a36bef985d |
ci(reskinnable-demo): gate the demo's four gates and its agent's lockfile
Nothing in CI built or type-checked this app. Leaving the root pnpm
workspace — which was right, it contains the canary line — also removed it
from every repo-wide sweep, because Nx discovers projects THROUGH the
workspace and there is no `workspaceLayout` in `nx.json`:
nx run-many -t build static_compat.yml does not see it
nx run-many -t check-types static_quality.yml does not see it
nx run-many -t test test_unit.yml does not see it
Both static workflows also carry `paths-ignore: ["examples/**"]`, so this
is a new workflow rather than an edit to either. It follows
`test_unit-showcase.yml`, which exists for the same reason applied to a
different directory.
Two jobs.
`gates` runs lint, typecheck, unit (2460 tests) and build, cheapest first,
inside the app because no root task reaches it. Measured locally at ~2
minutes of gates; the 20m budget is install headroom.
The build gate is the one that matters most and the one a developer can
least run: `next build` corrupts a concurrently running dev server's
PostCSS/Turbopack cache — measured, `globals.css` transforms to garbage
and every route 500s, and a dev-server restart does not clear it because
the corruption is on disk. CI is the only safe home for it. It needs no
env: the route constructs one agent per skin at module load and none of
them requires a key (banking's is an `HttpAgent` whose URL is never called
during a build).
`agent-resolve` syncs `agent/uv.lock` with `--frozen` and then asserts the
subagent surface is actually present. That is not hypothetical: until this
branch pinned it, `ag-ui-langgraph>=0.0.43` resolved the RELEASE, which
accepts no `emit_subagent_events` and exports no subagent symbols — the
demo's headline feature, failing silently because the flag is set as an
attribute on an object nobody reads. The assertion is on the CAPABILITY
rather than the version string, since a version assertion goes stale the
moment the pin moves and the surface is what must stay true.
One uncertainty is made into a gate rather than left to trust: this app
pins pnpm@10.10.0 while the root pins pnpm@10.33.4, and the older resolver
is load-bearing here — it still reads `pnpm.overrides` from package.json,
the only place `@ag-ui/core`, `@ag-ui/encoder` and `@ag-ui/proto` are
pinned to the canary (`@ag-ui/client` is a direct dependency; those three
are not). `pnpm/action-setup` is pointed at the app's package.json, and
because an unexpected action input is a WARNING in Actions rather than an
error, a step then compares `pnpm --version` against the pin and fails
loudly if they differ.
No `continue-on-error` and no `|| true` anywhere in the file.
|
||
|
renovate[bot]
|
d4f147aee8 | chore(deps): update depot/setup-action digest to 91bc849 | ||
|
Benjamin Taylor
|
6f58b2c6a4 |
fix(runtime): unify the Intelligence key name and publish the wiring (refs OSS-881)
Three names for one value were live in CopilotKit's own documentation, and following the wrong one with a CLI-provisioned project yields an undefined key: - `INTELLIGENCE_API_KEY` — what `copilotkit project select` writes, used by all 34 integration examples and the docs site. - `COPILOTKIT_INTELLIGENCE_API_KEY` — the seven Channels package READMEs and the packaged skills. Nothing ever read it. - `COPILOTKIT_API_KEY` — the Slack and Teams examples, and the TSDoc on `CopilotKitIntelligence` itself, which is what an IDE shows on hover. `INTELLIGENCE_API_KEY` wins, because it is the name the CLI provisions and changing it would break every scaffolded project in the wild. `COPILOTKIT_INTELLIGENCE_API_KEY` is retired outright — no code read it. `COPILOTKIT_API_KEY` stays readable as a deprecated alias in the two examples that consume it, so an existing `.env` keeps working, and is documented as deprecated everywhere it appears. The skills reference also documented `organizationId`, sourced from a fourth and fifth env name, as a `CopilotKitIntelligence` option. It is not one: `CopilotKitIntelligenceConfig` has no such field, so the copy-pasteable sample it appeared in would not compile. Removed from the samples, and the prose that told readers to fetch a value for it corrected. The Intelligence wiring itself was published only inside `node_modules/@copilotkit/runtime/skills/`, and the only docs pages showing `CopilotKitIntelligence` were the two Channels frontends — so a developer on the plain web path had no page to reach it from. Adds `/premium/connect-your-runtime`, which covers the wiring, how to confirm the credential is actually consumed, and the self-hosted two-URL rule. `scripts/validate-intelligence-env-names.ts` keeps this from drifting back. It runs unfiltered in CI on purpose: the two workflows that would otherwise cover it filter paths, and static/quality ignores `examples/**` — exactly where the deprecated alias lives. |
||
|
copilotkit-qa-bot[bot]
|
90d36a62c7 | Merge main into codex/fac-126-strands-ts-starter | ||
|
Benjamin Taylor
|
5c0150392f |
ci: stop Playwright browser installs shelling out to apt
Every Playwright install in CI passed `--with-deps`, which runs `apt-get update` before downloading the browser. apt on the runners cannot always reach azure.archive.ubuntu.com; when it can't it retries for many minutes, which is long enough to burn a job's whole `timeout-minutes` budget before a single test runs. GitHub renders that kill as "The operation was canceled", so it reads as a test failure rather than an infrastructure hang. Chromium's system libraries are already present on the Ubuntu runner images, and every one of these steps installs chromium only, so the browser download is all they need. Six jobs lose their apt dependency: test_unit, test_e2e-legacy-v1, test_e2e-showcase-on-demand, test_showcase-frontend-matrix, showcase_eval and showcase_capture-previews. Ports CopilotKit/website#529 to this repo. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> |
||
|
copilotkit-qa-bot[bot]
|
20e481b749 | fix: make Strands TypeScript starter smokeable | ||
|
copilotkit-qa-bot[bot]
|
bd91313517 | feat: add AWS Strands TypeScript starter | ||
|
Tyler Slaton
|
69bb0a9814 | fix(ci): stop enabling LangSmith tracing in the dojo e2e run (#6534) | ||
|
Benjamin Taylor
|
f07a7910d5 |
fix(ci): mock weather in the dojo e2e run, matching upstream
ag-ui's dojo-e2e sets AG_UI_MOCK_WEATHER=1 because the backend tool-rendering demos call the live open-meteo API, which rate-limits CI's shared egress IPs and hangs the suites. Our copy of the workflow drifted and never picked it up, so those suites hit the live API — a latent flake source, and a trace-divergence source now that the dojo asserts golden event traces. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> |
||
|
Benjamin Taylor
|
f6f6ed1872 |
fix(ci): stop enabling LangSmith tracing in the dojo e2e run
The dojo's new golden event-trace assertions (ag-ui #2392) compare STATE_SNAPSHOT metadata exactly, and our e2e run was polluting it. Injecting LANGSMITH_API_KEY makes langgraph-api force tracing on (LANGSMITH_CONTROL_PLANE_API_KEY defaults to LANGSMITH_API_KEY, which sets LANGSMITH_TRACING). The LangSmith client then merges every LANGSMITH_*/LANGCHAIN_* env var into each run's metadata dict, and langchain_core hands the tracer the same dict object the run config streams out — so `langgraph dev`'s LANGSMITH_LANGGRAPH_API_VARIANT=local_dev leaks into STATE_SNAPSHOT and every same-repo PR fails langgraph-python. Upstream ag-ui runs these suites keyless against LLMock, which is why its own CI is green on the same commit. Drop the key to restore parity; the dojo never needed it, since OPENAI_BASE_URL already points at LLMock. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> |
||
|
Ran Shem Tov
|
12cf10b9c7 | feat(showcase): deploy CrewAI conversational flows to staging | ||
|
Tyler Slaton
|
4093ab6289 |
docs(shell-docs): add LangSmith Platform deploy guide (LangGraph + ADK) (#6114)
## What Adds a **LangSmith Platform** deploy guide to the CopilotKit docs, modeled after the existing AWS AgentCore deploy page. It's a self-contained, agent-side guide: deploy a **LangGraph** or **Google ADK** agent to the LangSmith Platform, then point the CopilotKit Runtime at it. LangSmith has no frontend-hosting offering, so the guide covers only the agent side plus wiring the runtime. ## Pages - **Canonical:** `deploy/langsmith.mdx` — renders in the Overview → Deploy sidebar. - **Per-framework wrappers** (thin, like AgentCore): - `integrations/langgraph/deploy-langsmith.mdx` → `<Content framework="langgraph" .../>` - `integrations/adk/deploy-langsmith.mdx` → `<Content framework="adk" .../>` - Both registered in their `meta.json` under a new `---Deploy---` section. - **Shared walkthrough snippet:** `snippets/integrations/langsmith/index.mdx` — single source of truth for all three pages; framework-aware via the `Content` loader scope. Reuses the existing `langgraph-platform-deployment-tabs` snippet for the "grab your deployment URL" step. ## Structure (mirrors agentcore.mdx) Intro → How it works (ASCII flow `Browser → CopilotKit Runtime → LangSmith deployment → your agent`) → What you get → Quickstart `<Steps>` inside a `<TailoredContent>` (deploy-new vs already-deployed) → `<Callout>`s for the API key/URL and the LangSmith docs authority → framework tabs (LangGraph / Google ADK) for the deployable-app step → Troubleshooting `<Accordions>` → What's next `<Cards>`. ## Registry glue - Generalized the `Content` MDX component to accept an optional `partial` prop (defaults to the AgentCore partial; existing AgentCore wrappers unchanged). - Registered a `LangGraphPlatformDeploymentTabs` stub so the existing deployment-tabs snippet is reusable. ## Verification - Commands/flags (`uv tool install langgraph-cli`, `langgraph new --template new-langgraph-project-python`, `langgraph deploy --name/--deployment-type dedicated`, deployment API URL) verified against the live LangChain quickstart. - ADK path (`pip install "deployments-wrap-sdk[google-adk]"`, `saf_sdk.adk` `wrap()` + `LangsmithSessionService`, `langgraph.json` export) verified against the live [Deploy Google ADK agents](https://docs.langchain.com/langsmith/deploy-google-adk) guide. - Runtime wiring (`LangGraphAgent` from `@copilotkit/runtime/langgraph` with `deploymentUrl` / `graphId` / `langsmithApiKey`) matches the repo's LangGraph quickstart. - `oxfmt` (format) clean, `oxlint` exits 0, `tsc` clean; registry / search-href / link-rewrite tests pass. (Pre-existing failures in this worktree from an uninstalled `react-icons` and unfetched git-LFS assets are unrelated.) ## Note (small extra) The LangGraph `deploy-agentcore.mdx` wrapper already existed but was orphaned (not in any `meta.json`). The new `---Deploy---` section surfaces it alongside `deploy-langsmith`, matching how AWS Strands already exposes it. Ticket: GROW-540 |
||
|
Tyler Slaton
|
d542a29445 | fix(release): regenerate API manifest after version bumps | ||
|
renovate[bot]
|
6c43d9c699 | chore(deps): update reviewdog/action-actionlint action to v1.73.2 | ||
|
renovate[bot]
|
6023c008be | chore(deps): update astral-sh/setup-uv action to v10.0.1 | ||
|
Ran Shemtov
|
fa13d52502 | Merge branch 'main' into codex/crewai-full-d6 | ||
|
Tyler Slaton
|
cf59bc51ba | fix(showcase): decouple AEO synthetics from reverted contract | ||
|
Tyler Slaton
|
83bd1f9088 |
Revert "docs: define public AEO surface contract (#6458)"
This reverts commit |
||
|
Alem Tuzlak
|
4880afc846 |
test(skills): guard public skill API contracts (#6457)
## Summary - extend the existing public-skill drift suite to validate maintained setup assets against the generated public API manifest - fail when a skill imports an unpublished CopilotKit package or entrypoint, or a manifest-deprecated API - run the guard in the existing plugin-skills workflow when skills or the manifest change ## Why this matters Coding agents copy these skill assets directly into user projects. Mirror-sync tests prove that our duplicated skill files match, but they do not prove that the examples still reference packages and APIs we actually publish. A stale import can make CopilotKit fail at the first install or build step, which is exactly the kind of failure that prevents agents from choosing and successfully adopting us. This PR adds the smallest deterministic guard for that risk. It reuses our existing Vitest suite and canonical public API manifest; it does not introduce an eval harness, run agents, score behavior, collect metrics, add a provider, or add dependencies. ## Scope This is package-contract validation, not behavioral evaluation. Broader questions such as whether an agent follows a skill well, how many attempts it needs, and whether the generated application behaves correctly remain separate work and should start with a concrete decision the deterministic checks cannot answer. ## Verification - `pnpm exec vitest run scripts/__tests__/public-skill-drift.test.ts scripts/__tests__/sync-plugin-skills.test.ts` (17 tests) - `pnpm check:plugin-skills` - `pnpm check:public-api-manifest` - targeted TypeScript, oxfmt, and oxlint checks - mutation check: replacing `BuiltInAgent` with deprecated `BasicAgent` fails with the manifest-provided replacement Linear: PDX-320 |
||
|
Alem Tuzlak
|
47ad5e34a3 |
refactor(react-native)!: converge tool-call rendering onto CopilotKit's shared registry (#6438)
## What does this PR do?
`@copilotkit/react-native` maintained a **private tool-call render
registry** (`hooks/RenderToolContext.tsx`) alongside the canonical one
that `CopilotKitCoreReact` already provides — and which every React
Native app already ships, unused. This PR deletes the fork and points
React Native at the shared registry.
That fork caused three bugs:
| Bug | Symptom | Cause |
|---|---|---|
| **Tool renders never streamed** | A component registered with
`useRenderTool` / `useComponent` painted nothing until the tool call
completed | `CopilotChat` used `JSON.parse` on the argument buffer.
While a model writes a tool call that buffer is *invalid JSON by design*
— AG-UI delivers `TOOL_CALL_ARGS` deltas that are concatenated
client-side — so the parse threw on every delta, warned, and fell back
to `{}` |
| **`useComponent` rendered nowhere** | Silently, with no error | It
writes to core's registry; React Native's chat read React Native's
private `Map` |
| **Chat history degraded** | Navigating away from the registering
screen turned earlier tool calls into a `Called: <name>` placeholder |
The private `Map` deleted renderers on unmount; core deliberately keeps
them |
`@copilotkit/react-core` has used `partialJSONParse` on this path since
v2 shipped. React Native diverged because `useRenderToolCall` was
excluded from its re-exports on the stated grounds that it "depends on
DOM elements via `DefaultToolCallRenderer`" — a claim that was never
true of the hook itself. It was only ever reachable through the fat
`/v2` entry, whose weight is the real hazard (#4893). #5883 moved it
into `/v2/headless` on 2026-07-23; the exclusion comment was rewritten
the next day without revisiting the reason.
### What changed
- **One registry.** `useRenderTool` registers through `useFrontendTool`
into `CopilotKitCoreReact.renderToolCalls`. `CopilotChat` and any custom
surface consume react-core's `useRenderToolCall`.
- **Types are derived, not declared.** `RenderToolProps` is now
`React.ComponentProps<ReactToolCallRenderer<T>["render"]>`, so React
Native cannot drift from `ReactToolCallRenderer` — the contract every
registered renderer is actually invoked against. Change that contract
and `check-types` names every React Native renderer the change breaks.
React Native narrows only the *return* type to `ReactElement | null`,
which `FlatList`'s `renderItem` genuinely requires.
_Scope of that guarantee (corrected during review):_ it does **not**
extend to the type react-core publicly exports under the same name.
Web's `RenderToolProps<S>`
(`react-core/src/v2/hooks/use-render-tool.tsx`) is a separate
hand-declared union, generic over a schema, carrying arguments under
`parameters` (not `args`) and declaring `status` as string literals
rather than `ToolCallStatus` members. Both divergences are live today
and nothing type-checks them shut — the one place the shapes meet,
react-core's own bridge, compiles because a string-enum member is
assignable to its own literal type but not the reverse. Aligning web's
alias is a breaking web API change, filed separately.
- **`RenderToolContext.tsx` deleted** (−150 lines), along with 15 tests
that described the removed subsystem. One of them — `unregisters the
render function on unmount` — asserted the chat-history bug as a
requirement.
- **Two structural CI guards for #4893**, in opposite directions: a test
failing if any React Native source imports the fat `/v2` entry, and a
script failing if react-core's `/v2/headless` or `/v2/context` chunks
ever link shiki/mermaid/cytoscape/katex/streamdown. Both were verified
able to fail by deliberately introducing the regression. These are
*structural* assertions, not size budgets — `dev-docs/bundle-size.md`
freezes `limit` fields until OSS-122.
- **`react-native` added to the bundle-size glob**, which it had never
been in, plus a `size:headless` measurement.
React Native also gains capabilities it lacked: render props inferred
from your schema, `name`/`toolCallId` on render props, and `result` on
completed calls.
**Corrected during review — two capabilities this originally claimed are
not delivered:**
- **Wildcard (`"*"`) renderers do not work on React Native.** Because
`useRenderTool` routes through `useFrontendTool` (which calls
`addTool`), `name: "*"` registers a frontend tool literally named `*` —
advertised to the model, and colliding with core's separate
wildcard-executable-tool path. react-core's `useRenderTool` is
renderer-only and special-cases the wildcard; React Native's is not. The
guide now advises against it.
- **`followUp` (and `available`) are not forwarded**, and the handler's
`context` argument is dropped, so `stopAgent()`'s abort signal is
unreachable from an RN handler.
Both are tracked in § Known limitations for the follow-up that converges
React Native onto react-core's hooks — deleting RN's `useRenderTool` in
favour of re-exporting `useFrontendTool` (tool + renderer) and
react-core's `useRenderTool` (renderer-only, wildcard-capable). That is
an API change with its own migration note, so it is not in this PR.
### ⚠️ Breaking (in a minor)
`useRenderToolRegistry` and `RenderToolProvider` are **removed**. Both
are documented on the docs site, so this is a real break — see the
`BREAKING CHANGE:` footer on `db67ccf`, which is what the release notes
derive from, plus the rewritten reference pages.
```diff
- const registry = useRenderToolRegistry();
- const renderer = registry.get(toolCall.function.name);
- return renderer ? renderer({ args, status }) : null;
+ const renderToolCall = useRenderToolCall();
+ return renderToolCall({ toolCall });
```
Also note two semantic changes: `args` is `Partial<T>` **only** while
`status` is `"inProgress"`, and a render function is now captured at
registration — if it closes over changing values you must declare them
in `deps` (React Native previously refreshed the closure on every
render).
**Known limitation:** agent-scoped renderer resolution does not take
effect on React Native. `CopilotChatConfigurationProvider` is not in
RN's provider tree, so `agentId` always resolves to the default.
Renderers still resolve by name; two agents registering the same tool
name resolve arbitrarily. Filed separately.
### A data point worth recording
Adding `useRenderToolCall` to the measured headless entry moved the
bundle **92.8 kB → 92.7 kB**. Flat. The hook React Native spent months
not using was already inside the chunk every RN app resolves whole —
Metro doesn't tree-shake, so the fork never saved a byte. It cost them.
### Testing
- `@copilotkit/react-native`: **253 passing / 22 files** ·
`@copilotkit/react-core`: **1480 passing / 123 files** · `check-types`
and `build` green for both.
- Each of the three bugs has a deterministic test driving a real
`CopilotKitCoreReact` — no mocking of the code under test.
- Both #4893 guards carry mutation evidence: introduce the regression,
watch them fail, revert, watch them pass.
### Follow-up
`useRenderTool`'s JSDoc is split across two blocks, which orphans the
primary description from IDE hover (the `@param deps` warning still
surfaces). One-line fix, deliberately left out of the final fix wave.
## Related PRs and Issues
- **Supersedes #6346** (@davidmckayv) — its diagnoses were correct and
its test assertions are ported here, re-driven through the real registry
rather than a mocked local one. Credited via `Co-Authored-By` on
`4104bd1`.
- Addresses the React Native half of **#4893**.
- Builds on **#5883**, which created the lean `/v2/headless` entry this
PR consumes.
## Checklist
- [x] I have read the Contribution Guide
- [x] If the PR changes or adds functionality, I have updated the
relevant documentation
- [x] "Allow edits by maintainers" is checked
🤖 Generated with [Claude Code](https://claude.com/claude-code)
|
||
|
Tyler Slaton
|
f13fcb09e9 |
ci: add manual AEO production checks (#6459)
## Summary - add an on-demand production check for the website and docs discovery surfaces defined by #6458 - derive the ten in-scope routes and media types from the public contract instead of maintaining a second monitoring manifest - exercise those routes as four documented crawler user agents with a global concurrency cap of four - validate status, content type, canonical host, robots/sitemaps, one sampled sitemap link, LLM index links, and soft-404 behavior - retain failure evidence and provide a deliberate `exercise_alert` input for proving the `#oss-alerts` path ## Why this matters AEO is a production property, not a one-time content change. A correct repository can still deploy a broken canonical, HTML fallback, stale sitemap, or inaccessible LLM index. Those failures happen at the top of the agent-led growth funnel: if agents cannot reliably discover and verify CopilotKit, downstream recommendation and activation work never gets a chance to perform. This PR adds the smallest useful operating check for that risk. It is deliberately limited to PDX-340's website/docs scope. It does not monitor MCP, the CopilotKit capability document, raw Markdown, Open Graph, or JSON-LD. Existing deploy-parser utilities are reused where practical, requests run with bounded concurrency, and failures include the exact URL, crawler identity, observed status/type, and a bounded response excerpt. The workflow is intentionally manual at first. We should not create a scheduled noisy alarm while the website LLM endpoints are known red, and we should not claim Slack ownership until a deliberate failure proves the secret and alert path. A small follow-up can add the schedule after one normal run is green and one `exercise_alert` run reaches `#oss-alerts`. ## Stacked dependency - Depends on #6458; this PR is intentionally based on `codex/pdx-317-aeo-surface-contract`. ## Validation - `pnpm nx run @copilotkit/showcase-scripts:validate-aeo-contract --skip-nx-cache` - `pnpm nx run @copilotkit/showcase-scripts:test --skip-nx-cache -- __tests__/check-aeo-synthetics.test.ts __tests__/aeo-synthetics-wiring.test.ts __tests__/verify-deploy.drivers.test.ts` (102 tests) - targeted `oxfmt` and `oxlint` checks - `git diff --check` and commit hooks ## Live baseline (2026-08-12) The narrowed production command fails with eight records: four crawler identities × two website gaps. - `https://www.copilotkit.ai/llms.txt` returns HTTP 200 `text/html` with a noindex soft-404 instead of plain text - `https://www.copilotkit.ai/llms-full.txt` returns the same soft-404 The remaining website/docs targets pass: both home canonicals, both robots files, both sitemaps and sampled links, and both docs LLM indexes. The current failures are why this PR ships manual-first rather than enabling a schedule. ## Status PDX-340 remains In Progress until the website endpoints are fixed, a normal workflow run is green, the deliberate Slack alert reaches `#oss-alerts`, and a follow-up enables the agreed schedule. |
||
|
Tyler Slaton
|
d21aebc6e2 |
docs: define public AEO surface contract (#6458)
## Summary - publish a single shared, versioned technical contract for website, docs, and docs MCP AEO surfaces - publish the human policy through the existing shell-docs MDX pipeline at `/aeo` - expose the machine-readable contract at `/.well-known/copilotkit-capabilities/v1.json` - validate the contract with JSON Schema/Ajv plus narrow repository and CI cross-reference checks - run the actual shell-doc behavior tests in CI and assign external website and Pathfinder gaps to named owners ## Why this matters Answer engines and coding agents decide which source to trust from machine signals such as canonical hosts, stable URLs, response types, and consistent capability claims. When those signals disagree, CopilotKit can be classified incorrectly, cited from the wrong hostname, or skipped even when it is the right product. This PR gives those public surfaces a versioned source of truth. It separates standards, community conventions, and CopilotKit-specific guarantees; records real endpoint paths and media types; and makes ownership explicit when behavior lives in another repository or service. That gives us a reliable base for improving agent discovery without pretending one repository can enforce every public surface. The implementation deliberately uses the current docs architecture: `/aeo` is ordinary shell-docs MDX under `showcase/shell-docs/src/content/docs/`, not a bespoke page or the retired docs tree. Schema shape lives in JSON Schema, while the small TypeScript layer only checks relationships JSON Schema cannot express, such as whether referenced files and CI commands exist. ## Validation - `pnpm nx run @copilotkit/showcase-scripts:validate-aeo-contract --skip-nx-cache` - `pnpm nx run @copilotkit/showcase-scripts:test --skip-nx-cache -- __tests__/validate-aeo-contract.test.ts` (6 tests) - `npm --prefix showcase/shell-docs test -- src/app/sitemap.test.ts src/app/llms.txt/route.test.ts src/app/llms-full.txt/route.test.ts 'src/app/llms-mdx/[[...slug]]/route.test.ts' src/app/well-known/copilotkit-capabilities/v1.json/route.test.ts src/lib/runtime-config.test.ts src/lib/__tests__/next-config-redirects.test.ts` (43 tests) - `npm run typecheck` in `showcase/shell-docs` - `npm run build` in `showcase/shell-docs` - targeted `oxfmt`, `oxlint`, TypeScript, diff, and commit-hook checks ## External follow-ups - CopilotKit/website must link the same policy and fix `/llms.txt` plus `/llms-full.txt`, which returned 200 `text/html` soft-404 pages during the production audit - Pathfinder/docs MCP owners must define a machine-readable discovery surface; the current contract records `/sse` as the known transport without presenting transport availability as discovery ## Related - PDX-317 |
||
|
Jerel John Velarde
|
fe0e7cf28f |
feat(examples): add grok-generative-ui showcase
grok-4.6 runs xAI's X Search server-side, then composes the answer out of real React components through five CopilotKit frontend tools. Every post rendered is a real post the model found. Registers next.config.ts in the build-config allowlist and adds the row to the examples index. |
||
|
Ran Shem Tov
|
fe21ee439e | fix(showcase): repair CrewAI CI build gates | ||
|
Ran Shem Tov
|
04142ef4e2 | fix(ci): allowlist CrewAI conversational config | ||
|
Ran Shem Tov
|
a3ee26b424 | Merge remote-tracking branch 'origin/main' into codex/crewai-full-d6 | ||
|
Sam Julien
|
be3485d8f3 | fix(ci): narrow AEO synthetic rollout | ||
|
Sam Julien
|
a01b9f1034 | ci: monitor public AEO surfaces | ||
|
Sam Julien
|
25ce46ba5f | fix(docs): simplify AEO surface contract | ||
|
Sam Julien
|
9f2fb8e43b | docs: define public AEO surface contract |
