## 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
## 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
## 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)
## 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.
## 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
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.
react-native was missing from static_bundle_size.yml's package glob, so its
dist/ has never been measured despite being the consumer most exposed to the
#4893 regression (Metro does not tree-shake). This adds coverage:
- Extend the compressed-size-action glob to include react-native.
- New scripts/measure-headless.mjs: an esbuild-driven gzip signal for the
@copilotkit/react-native/headless entry, mirroring react-core's
measure-copilotchat.mjs (stdin + resolveDir, gzip sum, job-summary output).
- Wire a build + measure step into the copilotchat-import-size CI job.
First baseline: @copilotkit/react-native/headless = 92.8 kB gzip
(esbuild regression signal, not a Metro figure).
No limit fields (Phase 1 policy — see dev-docs/bundle-size.md).
esbuild added as a react-native devDependency (^0.27.0, matching react-core);
the root ">=0.25.4" override keeps the monorepo on a single esbuild (0.27.3).
Two corrections to the drafted script, verified by running it:
- Fed the entry via esbuild stdin with resolveDir=pkgRoot; a temp-dir entry
cannot resolve @copilotkit/react-native/headless through workspace node_modules.
- Dropped useRenderToolCall from the import list — the RN headless surface
deliberately does not export it (DOM-dependent; see src/index.ts).
Co-Authored-By: Claude <noreply@anthropic.com>
## What does this PR do?
Community PRs keep arriving with `.changeset/*.md` files even though the
repo migrated off Changesets to conventional-commit-driven releases.
`.changeset/` has now been deleted from `main` twice (`5afa55f067` on
2026-06-16, `1e5ba689e0` on 2026-07-29) and **five open PRs carry
changeset files today** (#6287, #6289, #6290, #6292, #6346).
Three mechanisms keep feeding it:
1. **Stale forks.** `rodboev/CopilotKit`'s default branch still contains
10 of the pre-cleanup `.changeset/*.md` debris files. Three of the five
open PRs come from that fork — the contributor's agent opens the repo,
sees a directory full of changesets, and adds one more. (No
`config.json`, and `@changesets/cli` isn't installed anywhere, so these
are hand-written by agents, not CLI output.)
2. **Merging stale PRs re-seeds `main`.** The two files Tyler removed in
`1e5ba689e0` arrived via 2026-06-10-authored branches (#2910, #5360)
merged on 2026-07-25 — they sat on `main` for four days, and anyone who
forked in that window inherited the directory. His hunch in that commit
message was right.
3. **Convention inference, uncontradicted.** #6346 is from a branch in
this repo, where `.changeset/` does *not* exist, and it still has one.
The repo reads as a Changesets repo: pnpm workspace monorepo,
per-package `CHANGELOG.md` in Changesets' exact `### Patch Changes`
output format, `chore: release monorepo vX.Y.Z` release PRs. Nothing in
`CONTRIBUTING.md`, the PR template, `AGENTS.md`, `CLAUDE.md`, or
`.claude/docs/` said otherwise, so the guess was well-supported.
This PR closes all three off:
- **`CONTRIBUTING.md`** — new "Changelogs and releases — do not add a
changeset" section: we did use Changesets, `scripts/release/` now builds
changelogs from commit subjects, `.changeset/*.md` is inert, write a
good conventional commit subject instead, and leave versions/changelogs
to maintainers. Includes a note to rebase old forks.
- **`AGENTS.md` / `CLAUDE.md`** — the same rule as an Essentials bullet.
This is the highest-leverage change: the contributors doing this are
coding agents, and agents load these files automatically while mostly
not reading `CONTRIBUTING.md`.
- **`static / check binaries`** — fail the PR on added `.changeset/*`
files, so this stops depending on review catching it (which is what
failed in July and restarted the loop). Added to the existing
forbidden-files gate rather than a new workflow: it already runs on
every PR to `main`, is fork-safe (`contents: read`, no secrets), and has
exactly this `git diff --name-only origin/BASE...HEAD` + `VIOLATIONS`
shape. Filters on `--diff-filter=AM` so a PR that *deletes* stale
changesets still passes.
- **`.oxfmtrc.json`** — drop the ignore entry for
`.github/actions/changesets-action/src/run.ts`, a path that hasn't
existed for a long time. It was the last grep-visible "we use
changesets" signal in a root config file.
## Related PRs and Issues
- Follows up `1e5ba689e0` ("fix: remove all changesets"), whose commit
message asked for exactly this: a durable record of the decision that
future agents can find.
- Open PRs that would be caught by the new gate: #6287, #6289, #6290,
#6292, #6346.
## Testing
Docs + CI-config change, so verification focused on the guard.
`actionlint` was run on the workflow, then the step body was extracted
with `yq` and executed against real branches.
**Lint / parse:**
```
$ actionlint .github/workflows/static_check-binaries.yml
actionlint: clean
$ python3 -c "import json; json.load(open('.oxfmtrc.json'))" # oxfmtrc still valid JSON
oxfmtrc JSON OK
```
**True positive** — real head of #6292, via `yq
'.jobs.check-binaries.steps[1].run'` piped to bash with `BASE_REF=main`:
```
::error::Changeset files detected in PR:
.changeset/enable-mcp-apps-tool-filters.md
This repo no longer uses Changesets — releases are driven by conventional commit subjects (see scripts/release/).
Nothing reads .changeset/*.md. Delete these files and describe the change in your commit subject instead.
See the 'Changelogs and releases' section of CONTRIBUTING.md.
This PR contains files that should not be committed (see the errors above).
Please remove them and update your .gitignore if needed.
exit=1
```
**True negative** — same script on this branch, which has five changed
files and no changesets:
```
$ git diff --name-only origin/main...HEAD
.github/workflows/static_check-binaries.yml
.oxfmtrc.json
AGENTS.md
CLAUDE.md
CONTRIBUTING.md
$ BASE_REF=main bash step.sh
No binary artifacts or oversized files detected.
exit=0
```
**Delete-safety** — a commit that *removes* changesets must not be
punished. Using the real cleanup commit (`8806f668d1...1e5ba689e0`):
```
unfiltered: with --diff-filter=AM (what the gate uses):
.changeset/coalesce-...md (empty)
.changeset/fix-parallel-...md
```
Not verified locally: the gate firing in real GitHub Actions — that
needs this PR's own CI run (the `static / check binaries` check on this
PR exercises the true-negative path).
🤖 Generated with [Claude Code](https://claude.com/claude-code)
## What
Adds the CopilotKit side of the [telemetry event
registry](https://github.com/CopilotKit/oss-path-to-production/blob/main/docs/telemetry-registry-publish-roadmap.md):
tooling + CI that generate this repo's registry **fragments** and open
path-limited PRs into `CopilotKit/oss-path-to-production`, where the
reconciler folds them into `telemetry-events.json`.
Two surfaces, two mechanisms (per the surface-owns-its-extractor
design):
| Surface | Events | Extraction | Trigger |
|---|---|---|---|
| **runtime** | 5 `oss.runtime.*` | **bespoke catalog** — reads the
`AnalyticsEvents` type map (names + properties), scans `capture()` sites
for `call_sites`; **fails loud if the v1/v2 catalogs diverge** | stable
**monorepo** release (`on: release`, tag `vX.Y.Z`) |
| **docs** (`showcase/shell-docs`) | 11 | **callee mode** — inline
`posthog.capture("name", {…})` literals; drops `$`-reserved events |
push to `main` touching `showcase/shell-docs/src/**` (excluding
`src/content`) |
## Key properties
- **Content-gated.** The emitter leaves the target fragment
byte-for-byte untouched when the extracted event set is unchanged, so a
PR opens **only when telemetry actually changes** — no per-release /
per-commit churn.
- **Reconciled canonical in every PR.** Both workflows run the
registry's `pnpm reconcile` and commit `telemetry-events.json` alongside
the fragment, matching the registry's shipped emitters — a fragment-only
PR fails its `telemetry-reconcile` staleness gate.
- **Least-privilege cross-repo token.** No explicit `owner` (defaults to
the app installation's org) + bare `repositories:
oss-path-to-production` + `contents`/`pull-requests` write only; mint
gated on a job-level env var (GitHub rejects `secrets.*` in `if:`).
- **zizmor clean** at CI's `--min-severity low` (one `cache-poisoning`
suppression, justified in `.github/zizmor.yml`: the workflow configures
no cache and publishes a PR, not build artifacts).
## Files
- `scripts/telemetry/extract.ts` — pure extraction (callee scan +
catalog reader), deterministic output.
- `scripts/telemetry/emit-fragment.ts` — CLI: `--surface runtime|docs
--out <path>`, assembles + content-gates the fragment.
- `scripts/__tests__/telemetry-fragment.test.ts` — 13 unit tests
(fixtures) + a loose real-catalog drift smoke test.
- `.github/workflows/telemetry-{runtime,docs}-fragment.yml` — the two CI
jobs.
## Testing
Rebased onto `main` (`55aaad21a6`) and revalidated end-to-end on
2026-08-05 — the branch had fallen 1345 commits behind.
**Unit / static**
- `vitest run scripts/__tests__/telemetry-fragment.test.ts` → **13/13
passed**.
- `tsc --noEmit --strict --esModuleInterop` over both scripts →
**clean** (`scripts/` has no tsconfig, so this is the ad-hoc
invocation).
- `oxlint scripts/telemetry` → **0 warnings, 0 errors**; `oxfmt --check`
→ **all files correctly formatted**.
- `zizmor --min-severity low --config .github/zizmor.yml
.github/workflows` (CI's exact invocation) → **No findings to report**
(32 ignored, 233 suppressed).
**Runtime surface — mechanism proven against the live rebased tree**
```
$ tsx scripts/telemetry/emit-fragment.ts --surface runtime --out /tmp/CopilotKit.runtime.json
runtime: wrote 5 events → /tmp/CopilotKit.runtime.json (released_in runtime@1.66.2)
```
Diffed event-for-event against the registry's committed
`CopilotKit.runtime.json`: **semantically identical** (same 5 events,
same `call_sites`, same `properties_seen`) — the only difference is
ordering, since the emitter sorts alphabetically and the hand-seeded
fragment is in catalog-declaration order. Confirmed the reorder is a
no-op at the canonical level (see below), so the first automated run
opens one reordering PR with an empty `telemetry-events.json` diff and
is quiet thereafter.
Also confirmed the catalog is still complete on current `main`: the only
`oss.*` event literals anywhere under `packages/runtime/src` +
`packages/shared/src` are the 5 catalog entries (43/22/12/9/9
occurrences), so no untyped event is being silently dropped. Both v1 and
v2 catalogs remain byte-identical, so the divergence guard passes.
**Docs surface**
```
$ tsx scripts/telemetry/emit-fragment.ts --surface docs --out /tmp/CopilotKit.docs.json
docs: wrote 11 events → /tmp/CopilotKit.docs.json (released_in shell-docs@5855496103)
```
11 events (up from 7 when this PR was authored — the docs site grew):
`cli_command_copied`, `docs_conversion_clicked`,
`docs_conversion_copied`, `docs.framework_selected`,
`docs.frontend_selected`, `docs.journey_continued`,
`hero_command_copied`, `markdown_copied`, `open_in_llm_clicked`,
`talk_to_us_clicked`, `try_for_free_clicked`. `$pageview` correctly
dropped.
**End-to-end against the real registry**
Dropped both emitted fragments into a clean
`oss-path-to-production@main` worktree and ran its own `pnpm reconcile`:
- Both fragments **validate against `fragment.schema.json`** (ajv, via
the reconciler's loader).
- Reconcile succeeded; `telemetry-events.json` grew by 216 lines with 11
new `"surface": "docs"` observations.
- **Zero `oss.runtime.*` entries changed** — confirming the runtime
fragment's reordering has no canonical effect.
## Fixed during revalidation
- **`add-paths` bug in the docs workflow (would have failed on first
run).** It ran `pnpm reconcile` but listed only the fragment in
`add-paths`, so its PR would have landed a fresh fragment beside a stale
`telemetry-events.json` and tripped the registry's `telemetry-reconcile`
staleness gate — the exact failure the runtime workflow was already
fixed for. Verified against the registry's shipped emitters: every
automated fragment PR there (`website.corp` #232/#220, Intelligence
surfaces #228) carries `telemetry-events.json` alongside its fragment.
- **Stale action pins.** Refreshed to the SHAs `main` now uses
everywhere: `actions/checkout` v7, `actions/setup-node` v7.0.0,
`pnpm/action-setup` v6.0.10.
- **Over-broad docs trigger.** Narrowed from `showcase/shell-docs/**` to
the code under `src/**`, excluding `src/content/**` — 1012 MDX + 140
JSON prose files with zero `.ts`/`.tsx`, none of which can hold a
`posthog.capture` call site. Prose edits no longer fire a full monorepo
install.
- **zizmor justification accuracy.** `setup-node` v7 adds a
`package-manager-cache` input defaulting to `true`; per its `action.yml`
it engages only when `package.json` declares **npm**, and this repo
declares pnpm — so the workflow is still cacheless and the suppression
still holds. Noted inline.
## Prerequisite — now satisfied
The registry App secrets (`TELEMETRY_REGISTRY_APP_ID`,
`TELEMETRY_REGISTRY_APP_PRIVATE_KEY`) are configured on this repo (added
2026-07-09), and `app/copilotkit-telemetry-bot` is demonstrably
installed on `oss-path-to-production` — it has been opening fragment PRs
there from other surfaces (#232, #228, #220). No further setup needed.
## Not in this PR
- The registry-side seed of the **docs** surface. The docs fragment
first appears via this workflow's initial run, which now also carries
the reconciled canonical, so it lands green.
- The **web-inspector** surface, hand-seeded in the registry since this
PR was authored, remains manual. Automating it is a follow-up.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
The repo migrated off @changesets/* to conventional-commit-driven releases
(scripts/release/ reads commit subjects from git log <lastTag>..HEAD), but
.changeset/ has been removed twice already (5afa55f067, 1e5ba689e0) and five
open PRs currently carry changeset files again. Two mechanisms keep feeding it:
contributor forks whose default branch still has the pre-cleanup .changeset/
debris, and plain convention inference — the repo reads as a Changesets repo
(pnpm monorepo, Changesets-formatted CHANGELOG.md files, "chore: release" PRs)
and nothing anywhere said otherwise.
- CONTRIBUTING.md: explain that we used Changesets, what replaced it, and what
to do instead (a good conventional commit subject).
- AGENTS.md / CLAUDE.md: same rule for coding agents, which author most of
these PRs and don't read CONTRIBUTING.md.
- static / check binaries: fail on added .changeset/* files, so this stops
depending on review catching it. Filters on added/modified only, so a PR
that deletes stale changesets still passes.
- .oxfmtrc.json: drop the ignore entry for the long-gone vendored
.github/actions/changesets-action, a stale "we use changesets" signal.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Revalidation against current main (the branch was 1345 commits behind):
- docs workflow ran `pnpm reconcile` but `add-paths` listed only the
fragment, so its PR would land a fresh fragment beside a stale
telemetry-events.json and fail the registry's telemetry-reconcile
staleness gate — the exact failure the runtime workflow was already
fixed for. Verified against the registry's shipped emitters: every
automated fragment PR there (website.corp, Intelligence surfaces)
carries telemetry-events.json alongside its fragment.
- Refresh the action pins to the SHAs main now uses everywhere
(checkout v7, setup-node v7.0.0, pnpm/action-setup v6.0.10).
- Narrow the docs trigger to code under shell-docs/src, excluding
src/content (1000+ MDX/JSON prose files that cannot hold a
posthog.capture call site) so prose edits stop firing a full install.
- Note in the zizmor justification why setup-node v7's new
package-manager-cache auto-path still leaves this workflow cacheless
(it engages only for npm-declared repos; this one declares pnpm).
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
A fragment-only PR fails oss-path-to-production's telemetry-reconcile gate (it
recomputes telemetry-events.json and fails on staleness). After emitting each
fragment, install the registry's deps and run pnpm reconcile, then include
telemetry-events.json in the PR alongside the fragment — matching the Intelligence
CLI + surface-emitter pattern.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The cross-repo fragment PRs must be authored by the dedicated telemetry-registry
GitHub App that's installed on oss-path-to-production (the same App the
Intelligence CLI release workflow uses), not CopilotKit's DEVOPS_BOT release bot.
Switch both workflows to app-id/private-key from secrets.TELEMETRY_REGISTRY_APP_ID
/ TELEMETRY_REGISTRY_APP_PRIVATE_KEY and gate the mint on the App ID env var.
These secrets must be added to the CopilotKit repo (they currently live only on
Intelligence).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Adds scripts/telemetry/ (emit-fragment.ts + extract.ts) and two CI workflows
that generate CopilotKit's telemetry-registry fragments and open path-limited
PRs into CopilotKit/oss-path-to-production:
- runtime (bespoke catalog): reads the AnalyticsEvents type map for event names
+ properties, scans capture() sites for call_sites, fails loud if the v1/v2
catalogs diverge. Triggered on stable monorepo release.
- docs (callee mode): extracts inline posthog.capture literals from
showcase/shell-docs (drops $-reserved events). Triggered on push to main
touching showcase/shell-docs/**.
Both are content-gated: the fragment is left untouched (and no PR opened) when
the event set is unchanged, so releases/edits don't churn the registry. Cross-
repo token follows the least-privilege recipe (no owner, bare repositories,
contents+PR write); mint gated on a job-level env var. zizmor clean (one
justified cache-poisoning suppression). 13 unit tests; tsc + oxlint clean.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
## Summary
Adds a `react-version` matrix axis (**18**, **19**) to the unit-test
workflow so react-core, react-ui, and a2ui-renderer are exercised across
the full **supported peer range** (`^18 || ^19`), not just the
repo-default React 19.
This is a **reconstruction of the durable parts of #4221**
(@tylerslaton) onto current `main`. That PR went stale (~5,000 commits
behind, conflicting) and never landed. Rather than rebase it, this
rebuilds its design fresh — and deliberately **scopes to the supported
React range**: React 17 is dropped, because it is no longer a supported
peer version and carried ~80% of the original PR's complexity
(polyfills, `use-sync-external-store` source shims, `jsx-runtime`
aliases, a legacy `renderHook` fallback).
## What surfaced
Dropping R17 and validating R18 revealed a **latent React 18
incompatibility on current `main`**: the `window = {}` test pattern
crashes React 18's concurrent renderer with `"Should not already be
working."` mid-commit, which then corrupts the scheduler for the rest of
the file — **22 failures across 5 files** under React 18. (React 19
happens to tolerate the empty-window swap, so it was invisible until
now.)
The original PR fixed this but mislabeled it R17-only; it's actually
needed for R18, a *supported* version. So the matrix earned its keep on
day one.
Replacing `window = {}` with `stubWindowLocation()` is the load-bearing
fix — it resolves the crash cascade. Separately, **two** tests differ
under R18 purely in *render scheduling*, and are handled by narrow
version gates:
| Test | React 18 behavior | Why it's not a bug |
|---|---|---|
| `renderCustomMessages` → "executes multiple renderers in order" |
`executionOrder` is `["first", "first"]` | Renderer double-invoke.
`second` still never runs, which is the actual contract. |
| `use-human-in-the-loop` → `statusHistory` | `inProgress → executing →
inProgress → complete` | Transient backwards transition from extra
effect runs. Start, end, and the set of observed statuses are all still
correct. |
**No assertion tolerates a different state value.** An earlier revision
of this PR also relaxed the three-turn state-snapshot assertion to
accept `Turn: 2` on R18; @tylerslaton correctly flagged that as an
observable-behavior difference rather than a scheduling artifact.
Re-verified against a real 18.3.1 install — the strict `Turn: 3`
assertion passes **25/25** consecutive runs — so that gate was
unnecessary and has been removed (`a227f46a8`). The two gates above were
re-tested the same way and both genuinely reproduce.
## Changes
| File | What |
|---|---|
| `.github/workflows/test_unit.yml` | `react-version: ["18","19"]` axis.
R19 installs frozen; R18 overrides the root `pnpm.overrides` React
version and installs unfrozen. Adds a guard verifying the installed
React matches the matrix leg, and suffixes `NX_CI_EXECUTION_ID` with the
React version. Layered on top of the existing nx-affected selection
logic. |
| `test-helpers/stub-window-location.ts` *(new)* | Clears
`window.location` (so the localhost auto-open-inspector heuristic skips)
while keeping the real jsdom window — the safe replacement for `window =
{}`. |
| `use-agent-error-state`, `CopilotKitProvider.onError`,
`CopilotKitProvider.test` | Swap `window = {}` for
`stubWindowLocation()`. |
| `use-human-in-the-loop.e2e`, `renderCustomMessages.e2e` | Two
React-version-gated assertions, both **render-scheduling only** (see
table above). State assertions stay strict on every leg. |
No dependency or lockfile changes. None of the R17-only machinery from
#4221.
## CI cost
Full runs go from 3 legs (node 20/22/24) to **6** (node × react). On
PRs, nx-affected still scopes what actually builds/tests; the full 6×
only hits `workflow_dispatch` or when `test_unit.yml` itself changes (so
this PR runs all 6). This is the honest price of adding R18 coverage.
## Testing
Run locally in a worktree via the exact install-override logic the
workflow uses — `react`/`react-dom` → 18.3.1,
`@types/react`/`@types/react-dom` → `^18`, `@testing-library/react` →
`^14.3.1`, `streamdown>react` → 18.3.1, then `pnpm install
--no-frozen-lockfile`. Installed versions confirmed by resolving from
`packages/react-core` (18.3.1 / 19.2.3, `@testing-library/react` 14.3.1
on the R18 leg).
| Check | Result |
|---|---|
| react-core full suite @ React 18.3.1 | **117 files, 1433/1433
passing** ✓ |
| react-core full suite @ React 19.2.3 | **117 files, 1433/1433
passing** ✓ |
| Strict `Turn: 3` state-snapshot assertion @ R18, ×25 runs | **25 pass
/ 0 fail** — gate removed as unnecessary |
| `executionOrder` gate reverted to strict @ R18 | **fails**
(`['first','first']`) — gate justified |
| HITL `statusHistory` gate reverted to strict @ R18 | **fails** (extra
`inProgress`) — gate justified |
| `oxlint` (project-aware) | **0 warnings, 0 errors** — unchanged from
`main` |
| `oxfmt --check` | clean |
| Workflow YAML parse + lefthook commit hooks (lint-fix, package tests,
commitlint) | green |
Before the `window` fix, the R18 leg was **22 failing across 5 files**;
it is now fully green.
Credit to @tylerslaton for the original design in #4221, and for
catching the over-relaxed state assertion in review.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
## Summary
Brings the `setup-slack-channel` skill into the set that `copilotkit
skills install` distributes, and narrows both it and
`copilotkit-channels` so they stop matching the same request.
## Why
The skill was merged into
[CopilotKit/channels-sdk#7](https://github.com/CopilotKit/channels-sdk/pull/7),
which makes it reachable from a channels-sdk checkout and nowhere else.
`copilotkit skills install` reads `CopilotKit/CopilotKit/skills`, so
until the skill lives here, no CLI user can get it.
No CLI change is needed to pick it up: skill names are free-form
(`--skill` is validated by regex only, with no allowlist) and the
default install is `--skill *`.
## How
**The skill is copied from the merged channels-sdk source**, with one
addition: a `version: 1.0.0` frontmatter field, so it matches the other
standalone skills in this repo (every one of them carries a version;
only the package-mirrored skills omit it). The body, references, and
manifest asset are otherwise unchanged. It stays browser-first and makes
no reference to the `copilotkit channels` commands, per the call to
defer those to the web app until they have more real-world usage.
**Both descriptions are narrowed** so the trigger overlap is gone:
| Skill | Owns | Hands off |
| --- | --- | --- |
| `copilotkit-channels` | The code half — declaring, wiring, and
customising a Channel. Assumes the provider app exists | First-time
Slack setup → `setup-slack-channel` |
| `setup-slack-channel` | The provider half — the Slack app, its tokens,
attaching it to a Channel | Code questions → `copilotkit-channels` |
Before this, both matched "connect my agent to Slack" and the agent
picked whichever it read first. That collision was invisible in
channels-sdk, where `setup-slack-channel` is the only skill present; it
becomes live the moment both ship in the installed set.
## Notes for reviewers
- **Scope is Slack only.** A Teams sibling is deliberately a separate
pass.
- **No existing skill content changes** — the `copilotkit-channels` diff
is its frontmatter description and nothing else.
- Two known follow-ups are tracked and intentionally not addressed here:
[channels-sdk#9](https://github.com/CopilotKit/channels-sdk/issues/9)
(CLI-capability claims, deferred by decision) and
[channels-sdk#2](https://github.com/CopilotKit/channels-sdk/issues/2)
(`build-channels-bot` staleness, unrelated).
Refs CopilotKit/channels-sdk#10
## Added during the `main` merge
Resolving the conflict surfaced a second, unrelated problem that had to
be fixed for this PR to be safe to land.
`skills/setup-slack-channel` is a **standalone** skill — it has no
`packages/*/skills/` source. `scripts/sync-plugin-skills.ts` treats any
such directory as an orphan unless it is listed in
`RESERVED_LIFECYCLE_SLUGS`, which this one was not. Verified against the
pre-fix script:
- `pnpm check:plugin-skills` → exit 1, `orphan file(s) in mirror:
skills/setup-slack-channel`
- `pnpm sync:plugin-skills` (write mode) → **recursively deleted all 8
files of the new skill**
The `plugin-skills-check` workflow's path filter does not match
`skills/setup-slack-channel/**`, so this PR would not have caught it —
it would have gone red on the next unrelated PR that touched the script
or a package skill, or silently eaten the skill on the next sync run.
Fix is two lines: add the slug to `RESERVED_LIFECYCLE_SLUGS`, and move
the paired `size` assertion in
`scripts/__tests__/sync-plugin-skills.test.ts` from 9 to 10. The test
file already documents this exact hazard in a comment.
### Conflict resolution
The only conflict was the `copilotkit-channels` frontmatter description,
which #6320 rewrote in parallel. The two sides disagreed about Teams:
this branch said the skill "assumes the provider app already exists",
while #6320 established that Teams provider setup **is** this skill's
job because the CLI or dashboard wizard performs it. The resolution
keeps this branch's code-half framing and the `setup-slack-channel`
handoff, but scopes that handoff to *first-time Slack app creation* only
— so it contradicts neither #6320's Teams sections nor the Slack
provider troubleshooting that stays in this file. Took #6320's `version:
1.1.0`.
Addresses review on #6340.
Interactivity is no longer disabled on the managed path. The shared generator
emits `interactivity.is_enabled: true` with an Intelligence-hosted request URL
(Intelligence `libs/channels-setup/src/slack.ts:209-211`) and the ingress
handles `block_actions` (`apps/app-api/src/routes/channels-routes.ts:868`), so
HITL buttons and selects do fire. The skill's own bundled manifest asset already
said `is_enabled: true`, so the prose contradicted the file shipped beside it.
What is still undelivered is `slash_commands` (absent from the generator) and
`view_submission` (`apps/app-api/src/channels/slack-ingress.ts:1050`), so the
`onCommand` / `onModalSubmit` warnings stay. Corrected in all three places that
claimed otherwise, and the troubleshooting entry now tells the reader a dead
button is a real failure rather than a capability limit.
Browser-only framing is now a routing instruction rather than an architectural
claim, since `copilotkit channels add` does create the Channel and attach the
adapter. Same outcome, but it no longer contradicts `--help` for an agent that
was told to check it.
Trigger scope is narrowed in the frontmatter description instead of rewriting
Phase 0. The phases assume OpenTag conventions (`app/channel.tsx`, `app/env.ts`,
`INTELLIGENCE_CHANNEL_NAME`, an agent on port 8123), which are not what
`copilotkit init` scaffolds — naming that in the description keeps the skill from
firing on any "connect my agent to Slack" once it installs into customer repos.
Also widens the plugin-skills-check path filter to `skills/**` rather than
adding the one new slug. The orphan scan reads the whole mirror, so enumerating
individual directories is what let this PR's own blocker go untested and would
have armed it again for the next standalone skill.
`bun-version: latest` let a Bun release change module-resolution behaviour
between runs. 1.3.14 is the version the recent passing and failing runs both
resolved, so pin it and make the job reproducible.
The repo gates which build-config files may exist (next.config, vite.config,
webpack.config and friends) so a new bundler config cannot appear unreviewed.
A new app needs its next.config.mjs registered.
Kept as its own commit because the check's own failure message asks for
CODEOWNERS approval when the allowlist changes — isolating it means that
approval applies to exactly one reviewable line rather than being buried in
the app scaffold.
The publish job reinstalled all 4608 projects' dependencies (~41s) to run
two things: `pnpm tsx` and `pnpm pack`.
A root-only install is NOT sufficient — verified locally that pnpm pack
then dies with ERR_PNPM_CANNOT_RESOLVE_WORKSPACE_PROTOCOL, because pack
resolves each package's `workspace:` deps into real version ranges and
needs its workspace siblings installed to do it. That resolution is what
makes cross-scope canary deps pin the same-run version, so it is
load-bearing.
The true minimum is root + packages/**: measured 17s vs 46s locally, and
the packed tarball still carries resolved ranges (^0.4.0, ^1.64.1) with no
leftover workspace: refs. Everything trimmed is examples/ and showcase/ app
dependencies that no publish step touches.
Safe because no publishable package declares prepack or prepare, so pnpm
pack runs no lifecycle scripts; voice's prepublishOnly fires for neither
pnpm pack nor `npm publish <tarball>`.
Stable keeps the full install — its dependency surface is wider
(lib/notion.js, the umbrella verifier's root script) and it is the
highest-stakes path.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
canary.yml mirrors the source branch to a unique
canary/<slug>-<run_id>-<attempt> ref, and Actions scopes cache entries to
the writing branch (plus the default branch). A cache saved from a canary
ref is therefore unreachable by every later canary — measured at 874 MiB
of orphan per run, competing for the repo's shared 10 GB budget and
evicting entries other workflows depend on.
It also cost more than it bought: 20s + 26s of post-job saves against a
25s faster install.
Canaries now restore read-only (free win when main has an entry, zero
cost and zero pollution when it doesn't); stable releases, which run on
main where a write is durable and reused, do the writing.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The canary flow took ~11.5 min steady-state (and 20 min in an observed
run). Measured from run 30473499191, the time went to five avoidable
places rather than to real work.
1. `npx --yes npm@11.15.0 publish` ran per package, and npx re-resolves
the spec against the registry on EVERY invocation: ~16s of each
package's ~21s. A 9-package channels canary paid ~2.4 min of pure npx
overhead; a 16-package monorepo release paid over 4 min. Hoist the
pinned npm into lib/npm-cli.ts, install it once into a throwaway
prefix, and reuse the binary.
2. publish-release.yml was the only workflow in the repo with no pnpm
store cache, so all three jobs installed 4608 packages cold every
time. Usually ~45s each, but registry-bandwidth bound and heavy
tailed: the observed run spent 9m08s here on tarballs arriving at
2-49 KiB/s. Add the same node-version-keyed cache the rest of CI uses.
3. The notify job ran for canaries only to compute "post nothing" — the
builder already returns should_post=false for mode=prerelease and the
self-watchdog is already gated off. ~85s of dead work on the critical
path, since canary.yml waits for the whole run. Skip the job, keeping
it reachable for a python_publish dispatch.
4. The build job fetched full history for canaries, which need none (no
tag, no GH Release, no release-note commit range, and `nx run-many`
resolves no merge base). That rode along in the 837 MiB workspace
artifact too. Shallow-fetch prereleases; stable keeps depth 0 because
its publish job pushes tags out of that artifact's .git.
5. Two smaller ones: the artifact was gzipped and then re-deflated into
the artifact zip (compression-level: 0), and the orchestrator's
run-discovery loop slept 6s before its first poll.
Verified: 143 release-script tests pass (6 new for the npm-cli helper),
actionlint + shellcheck + the scope-dropdown guard are clean, the
prerelease dry-run path still enumerates all 9 channels packages, and a
live probe confirms the helper installs npm 11.15.0 once (3.2s) and
memoizes thereafter (0ms).
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
## The race, with evidence
Three PRs merged within 34 seconds on 2026-07-26. `Showcase: Build &
Push` has **no concurrency group** (deliberately), so all three ran
simultaneously and raced to push the same `:latest` tags.
| run | commit | PR | start → end |
|---|---|---|---|
| `30190815370` | `7b28934387` | #6162 | 06:18:05 → 06:29:44 |
| `30190823203` | `59f275eedc` | #6161 | 06:18:21 → 06:29:44 |
| `30190831480` | `db75a04837` | #6158 | 06:18:39 → **06:29:13** ←
newest, finished FIRST |
The newest commit finished first, so the older builds overwrote its
`:latest`. Per-service job completion times — older beating newer on
every shared slot:
| service | newer (`db75a04837`) | older (`59f275eedc`) | older won by |
|---|---|---|---|
| `shell-dashboard` | 06:25:33 | 06:25:34 | +1s |
| `showcase-harness` | 06:27:51 | 06:27:55 | +4s |
| `shell` | 06:27:17 | 06:27:28 | +11s |
| `shell-dojo` | 06:25:10 | 06:25:26 | +16s |
**All three runs reported `success`.** Staging served pre-#6158 code
while CI, the redeploy gate and deploy verification all looked clean.
Same failure class as #6171: a success that doesn't mean what it says.
## What I verified in YAML vs took on trust
Verified by reading the files / querying the API:
- **Tagging** — `showcase_build.yml` pushed `:latest` **and** `:${{
github.sha }}` in one `depot/build-push-action` step, in both the
`build` and `build-starters` matrices. **A per-commit sha tag already
existed**; confirmed in GHCR (`showcase-shell-dashboard` has digests
tagged `db75a04837…`, `59f275eedc…`, `d28384a2eb…`).
- **Nothing serialized the pushes.** No concurrency group; confirmed the
header comment states this is intentional.
- **Deploy consumes `:latest`** — `verify-railway-image-refs.ts` is the
SSOT assertion: staging is `ghcr.io/copilotkit/<repo>:latest` (mutable),
**prod is `ghcr.io/copilotkit/<repo>@sha256:<digest>` (already immutably
pinned)**. So this race is **staging-only**; prod was never exposed.
- **`Showcase: Verify Deploy` structurally cannot catch it.** It is a
health probe; it asserts no digest or commit provenance anywhere. Its
#6171 per-commit concurrency key is about *which run verifies*, not
*what image is running*. A stale-but-healthy service passes.
- **The racing runs build DISJOINT service sets** (see below) — I pulled
the actual job lists.
Taken on trust: nothing material. The issue description matched the API
on every point I checked.
## Why NOT a concurrency group
`detect-changes` builds a **per-push, path-filtered** matrix, so
concurrent runs build overlapping but **non-identical** service sets:
- `7b28934387` → ag2, agno, built-in-agent, claude-sdk-python,
claude-sdk-typescript, crewai-crews, langgraph-fastapi,
langgraph-python, langroid, llamaindex, mastra, pydantic-ai, shell-docs,
spring-ai, strands (**15**)
- `db75a04837` → crewai-crews, llamaindex, shell, shell-dashboard,
shell-docs, shell-dojo, showcase-harness (**7**)
`cancel-in-progress: true` would have cancelled the `7b28934387` run and
the ~10 services **only it builds would never have shipped** — trading a
stale-image bug for a never-shipped bug. Per [GitHub's
docs](https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax#concurrency),
`cancel-in-progress: false` is no better: *"Any previously pending job
or workflow in the concurrency group will be canceled"* — with three
rapid merges the **middle** commit's build is dropped outright. GitHub
also does not guarantee FIFO ordering of queued runs.
Concurrent runs here are **not redundant**, so they must not be
cancelled.
**Re the #6171 interaction:** this design does **not** use
`cancel-in-progress`, so no build is ever superseded-and-cancelled and
the cancelled-slot notifier is never tripped by this change. That
interaction stays theoretical — deliberately.
## The design
Make the one shared mutable resource monotonic instead of serializing
the fleet.
1. The build step pushes **only** the immutable `:<sha>` tag, plus an
`org.opencontainers.image.revision` label.
2. A guard resolves the commit behind the current `:latest`, asks GitHub
`compare/<theirs>...<ours>`, and advances `:latest` (registry-side
retag, no pull) **unless ours is `behind`** — i.e. `:latest` already
holds a descendant and moving it would roll staging back.
**Fails open by design.** No `:latest` yet, unlabelled legacy image,
unreachable API, diverged history → advance. A stuck `:latest` is the
very failure being fixed, so it declines only on *positive proof* of
regression.
**Placement:** in `redeploy-staging` / `redeploy-staging-starters`,
immediately before the Railway pull that consumes `:latest` — not per
build slot. Those jobs already have Node (build slots do **not**, so
per-slot would mean an unpinned `npx tsx` fetch on ~50 parallel
runners), and deciding right before the pull makes the window as narrow
as possible. The image list is the **same matrix ∩ build-success
intersection** that decides what gets redeployed, so a failed build can
never move a tag.
Also adds `showcase_build.yml` to `showcase_validate.yml`'s trigger
paths — the new test asserts against that file's live text, and without
the path a PR re-adding `:latest` would never run the test that catches
it.
## Tradeoffs / what stays open
- **Residual sub-second TOCTOU.** GHCR has no compare-and-swap on tags,
so two runs reading `:latest` simultaneously could still both advance.
This narrows the window from the whole build (~10 min) to inspect→retag.
Fully closing it means retiring the mutable staging tag and pinning
staging to digests the way prod already is — a change to the Railway
image-ref SSOT contract, not a workflow change. **Recommended
follow-up.**
- **The guard is inert for one build per image.** Today's `:latest`
images carry no labels (verified: `showcase-shell-dashboard:latest` has
no `Labels` at all), so the first post-merge build fails open and
advances unconditionally — same as today. Protection starts from the
second build of each image.
- Failure to retag exits non-zero, redding the redeploy job and stopping
the deploy. That is intended: redeploying against a tag that did not
move is exactly the silent false green being fixed.
## Proof
**Red/green on the live YAML.** `advance-latest-tag.test.ts` parses the
real `showcase_build.yml` (extending #6171's `redeploy-guard.test.ts`
pattern). Reverting the workflow to its pre-fix state: **14 failed / 23
passed**. With the fix: **37 passed**. Full `showcase/scripts` suite:
**2382 passed, 73 files**.
**The load-bearing predicate, verified live against the real incident
commits:**
```
compare/db75a04837...59f275eedc => behind (older run arriving late → DECLINE)
compare/59f275eedc...db75a04837 => ahead (newer run → advance)
compare/db75a04837...db75a04837 => identical
```
**Label reading, verified against a real multi-platform registry image**
— `docker buildx imagetools inspect ghcr.io/astral-sh/uv:latest` piped
through `extractRevisionLabel()` returns
`3010295ae7ff572de459987ad70db315a62ecd61`, matching `jq` exactly. The
platform-keyed shape is handled.
**Shell/jq transforms** exercised directly, including the empty-CSV edge
case (empty → empty, step skipped by its `if:`).
**Lint:** `actionlint` finding counts byte-identical to the pre-change
baseline (no new findings; the 11 pre-existing are unrelated). `zizmor
--min-severity low` with the repo config: **no findings**.
**Typecheck:** both new files are in `showcase/scripts/tsconfig.json`'s
include set and produce **zero** errors. Worth stating plainly: `nx
run-many -t check-types` **does not reach `showcase/scripts`** — the
project isn't in the nx graph and has no `check-types` target (there are
9 pre-existing type errors in sibling files, which is how I confirmed
it). So the typecheck above is mine, not CI's. The *tests* are gated:
`showcase_validate.yml` runs bare `pnpm exec vitest run` in
`showcase/scripts`, which auto-discovers the new file.
### What I could NOT prove
**I did not construct a real concurrent race on scratch branches.**
Doing it faithfully needs two builds pushing the same GHCR repo with
controlled finish ordering, which means merging to `main` — the only
branch the build workflow triggers on. No run IDs for a live race
demonstration; I am not implying one.
Unproven until this runs on main: that `docker buildx imagetools create`
retags cleanly under the runner's GHCR credentials, and that `npx tsx`
behaves in the redeploy jobs (it is already the established invocation
there — `redeploy-env.ts` — so this is low risk, not zero).
## Normal single-merge builds are unaffected
No concurrency group is added, so nothing queues or cancels. A lone
merge finds `:latest` at its own parent → `ahead` → advances, exactly as
before. Cost is one `imagetools inspect` + one `gh api` + one
registry-side retag per built service, in a job that already exists — no
extra job, no extra checkout, no change to build parallelism.
---
Branched from `db75a04837`; #6156/#6159 landed after, so this will need
main merged in before it goes green.
Probable conflict with the concurrent `git lfs pull` work in
`showcase_validate.yml` — my edit there is only the top-level `on:
paths:` list, so it should merge cleanly, but flagging it.
Tyler Slaton