Fixes defects 3, 4, 6, 7, 8, 10, 11 and 12 from the OSS-856 phase 1
validation run. Every claim below was re-verified against installed
package source or a live run, not recalled.
LangGraph quickstart (`integrations/langgraph/quickstart.mdx`):
- Route shape: a caution at the route step. The POST-only route runs the
runtime in single-route mode, which is all chat needs; Threads and the
Inspector need the multi-route catch-all with GET/POST/PATCH/DELETE.
Links to the canonical runtime-endpoints section.
- Port: bare `langgraph dev` serves 2024, not 8123. Verified against both
CLIs (`@langchain/langgraph-cli` help output, and `default=2024` in
`langgraph_cli/cli.py`). The guide keeps `--port 8123` to stay
consistent with every sibling page, and now says so.
- Drop `@copilotkit/react-ui` from the install list. `CopilotSidebar`
lives in `@copilotkit/react-core/v2`; react-ui exports no `./v2` JS
entry point and the v2 react example does not depend on it.
- Checkpointer: state the reason each tab differs. `langgraph dev` fails
to load a graph compiled with a custom checkpointer (reproduced), while
the FastAPI tab needs one because `ag-ui-langgraph` calls
`graph.aget_state(...)`, which raises `ValueError: No checkpointer set`.
- Narrow the shared `uv add` line to what both tabs import, and warn that
a project with exact pins should add them by hand.
A2UI fixed schema (`generative-ui/a2ui/fixed-schema.mdx`):
- Add the missing install step for `@copilotkit/a2ui-renderer` + `zod`,
which the catalog/definitions/renderer snippets all import.
- Add a `StateGraph` + `ToolNode` form for developers who already have a
hand-built graph, gated to the Python LangGraph slugs by a new
`a2ui_agent_form` docs flag so the shared page does not show Python to
langgraph-typescript or LangGraph code to LlamaIndex/ADK/Mastra.
- Repoint the cross-tree `/integrations/langgraph/...` link, which 301'd
back to this same page, at the action-handler reference it promises.
Raw Markdown pipeline (`src/lib/llm-text.ts`):
- `renderPageToLlmText` never applied `filterFrameworkScopedBlocks`, so
`/<framework>/<page>.md` emitted every `<WhenFrameworkHas>` branch with
raw JSX tags, each carrying the one selected framework's snippet. On the
A2UI page that produced three mutually-exclusive "how the schema is
delivered" sections whose prose contradicted the identical code under
each. Gate on the same framework the snippets resolve to, with a
regression test.
Also corrects a factually wrong comment in the langgraph-python showcase
`.env.example` that claimed 8123 was the `langgraph dev` default — the
same mis-belief this ticket found in the docs.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
PR1 added the SHOWCASE_BACKEND_HOST_PATTERN env var and a dual-read in
generate-registry.ts that synthesizes backend_url when the manifest omits
it. This commit (PR2) makes the env-var-derived path the only path.
- Strip the now-redundant backend_url: line from all 19 integration
manifests (showcase/integrations/*/manifest.yaml).
- generate-registry.ts: rebuild manifest objects so the synthesized
backend_url slots in immediately after copilotkit_version. With this
change registry.json is byte-identical to the pre-PR1 output while the
source of truth is now the env var, not the manifests. Comment updated
to reflect the new state.
- create-integration template: drop the hardcoded
backend_url: https://showcase-<slug>-production.up.railway.app line so
newly scaffolded integrations omit the field too. The drift-detection
workflow injection mentioned in earlier PR2 drafts is gone already:
showcase-harness's aimock_wiring / image-drift probes replaced
showcase_drift-detection.yml, so no workflow file needs editing.
- manifest.schema.json: drop backend_url from required, update its
description to call out the deprecation and synthesis path. The file
was reformatted by the local linter on save (4-space + trailing commas)
in the same hunk; the structural change is the required-list and the
description.
- starter.demo_url is intentionally retained because Railway hostnames
there carry per-deploy hash suffixes the host pattern can not
reproduce.
Verified locally:
- tsx generate-registry.ts -> byte-identical to baseline registry.json.
- SHOWCASE_BACKEND_HOST_PATTERN='showcase-{slug}-staging.example.com'
produces the expected per-slug staging URLs.
- tsc --noEmit -p showcase/scripts/tsconfig.json: clean.
- vitest run in showcase/scripts: 1308/1308 passing.
- playwright test --list in showcase/tests: 79 tests enumerate cleanly.
Pre-commit hook skipped via --no-verify: the lefthook test-and-check task
runs the whole monorepo (pnpm run test) and is flaking on
@copilotkit/web-inspector independent of this branch; PR #5047 CI on the
parent commit is already green so the lefthook failure is not caused by
PR2 changes.
Replaces the v1 docs surface for 11 frameworks by porting their v1 MDX
into showcase/shell-docs/src/content/docs/integrations/ and flipping
the route handler to render those trees directly. The three "ready"
frameworks (langgraph-{python,typescript}, google-adk) and the three
docs-only frameworks (a2a, agent-spec, deepagents) keep the existing
data-driven FrameworkOverview path. Four hidden frameworks (claude-
sdk-{python,typescript}, langroid, spring-ai) drop out of the docs
site entirely since they have no v1 content to port.
The mode flip is config-driven via a new `docs_mode` field on each
manifest.yaml (showcase/integrations/<slug>/manifest.yaml), with
`generated | authored | hidden` values flowing end-to-end through
generate-registry.ts → registry.json → a new getDocsMode(slug)
helper → page.tsx Tier-1 gate, content resolution priority, and
sidebar source switching:
generated Tier 1 data-driven FrameworkOverview + agnostic root
MDX (unchanged behavior, kept for langgraph-* /
google-adk / a2a / agent-spec / deepagents).
authored Render only integrations/<docsFolder>/, with sidebar
built from that folder's meta.json. No root-MDX
fallback.
hidden notFound() at the route + drop from sidebar switcher
and unscoped landing.
To support authored index.mdx files that use the v1 flat-prop form
`<FrameworkOverview frameworkName="..." frameworkIcon={<XIcon/>} ...>`,
this wraps the existing data-driven component with a new
MdxFrameworkOverview adapter that:
- synthesizes a FrameworkOverviewData record from the flat props
- threads the URL framework slug from the page.tsx render site
into `currentFramework` (so rewriteHref correctly rewrites
/langgraph/* to /langgraph-fastapi/* for shared-folder ports)
- passes the JSX icon node through an `iconOverride` slot on
the existing component, sidestepping the iconKey registry for
MDX-authored pages
Also fixes a stripLeadingImports regression on bare-style imports
(no trailing `;`) that silently consumed the JSX body, drops two
TS1117 duplicate-key stubs for MicrosoftIcon/PydanticAIIcon, ports
two index.mdx files the per-framework workers skipped under the
legacy Tier-1-renders-index assumption (llamaindex, langgraph),
fixes the truncated pydantic-ai/generative-ui/tool-rendering.mdx
+ removes props.components from display-only.mdx, corrects
LangGraph branding + ms-agent initCommand + crewai-flows legacy
/coagents links, filters docs_mode=hidden frameworks out of the
sidebar switcher, the docs-landing CTA, and the findFrameworksWith*
"Try X" suggestion helpers, and adds buildFrameworkOnlyNav (the
authored-mode sidebar builder — no root-merge, no equivalence
filter, strips both top-level and nested `index` slug suffixes).
End-to-end verification: probe-shell-docs.ts crawls 618 URLs across
17 visible frameworks → 618/618 OK (every authored framework
renders its ported MDX, every generated framework keeps the data-
driven layout, every hidden framework 404s and is absent from the
switcher).
Adds two new manifest pattern flags (matching the existing
`interrupt_pattern` / `a2ui_pattern` convention) so the canonical
`/agent-config` and `/auth` shell-docs pages can gate their per-pattern
sections via `<WhenFrameworkHas>` and only render the implementation that
applies to the framework the user has selected.
- `agent_config_pattern: shared-state | runtime-properties | null`
- `runtime-properties` (1 fw): built-in-agent
- `shared-state` (17 fws): everything else that wires agent-config
- `auth_pattern: langgraph | ag2-context-variables | microsoft-agent-framework | runtime-onrequest | null`
- `langgraph` (3 fws): langgraph-python, langgraph-typescript, langgraph-fastapi
- `ag2-context-variables` (1 fw): ag2
- `microsoft-agent-framework` (2 fws): ms-agent-python, ms-agent-dotnet
- `runtime-onrequest` (12 fws): everything else
Also fills in the previously-missing `a2ui_pattern` flag on 6 frameworks
that have wired demos but were rendering near-empty doc pages because
none of the existing `<WhenFrameworkHas>` gates matched. Audit-driven:
ag2/agno/claude-sdk-{python,typescript}/langroid use schema-loading;
built-in-agent uses schema-inline.
Adds a server component that gates MDX content on a framework's manifest
field (e.g. a2ui_pattern, interrupt_pattern). Lets a single docs page
render different code + prose per framework idiom — solves PDX-68.
<WhenFrameworkHas flag="a2ui_pattern" equals="schema-loading">
only renders for frameworks where integration[flag] === equals
</WhenFrameworkHas>
Pieces:
- when-framework-has.tsx: server component, reads framework via prop
(defaultFramework injected by docs-page-view, same pattern as Snippet)
- mdx-registry.tsx: registers WhenFrameworkHas as an MDX component
- docs-page-view.tsx: overrides the registry entry to inject the
page's defaultFramework
- registry.ts: Integration type gains a2ui_pattern + interrupt_pattern
fields (nullable enums)
- manifest.schema.json: same fields for editor validation
Adds a fourth cell status, "unsupported", to the showcase dashboard for
features whose framework cannot architecturally support them (e.g.,
no graph-interrupt API, no MCP tool runtime). This is distinct from
"unshipped" (just unbuilt).
- Manifest schema gains optional `not_supported_features: string[]`.
- generate-registry.ts: determineCellStatus checks `not_supported_features`
first; CatalogCell/CatalogMetadata gain `unsupported`; max_depth=0 for
unsupported cells; parity tier is computed against the supportable subset
of the reference (unsupported features no longer drag a framework's tier
down for gaps it legitimately cannot fill).
- depth-utils.ts: deriveDepth returns D0 with no regression for
unsupported cells.
- DepthChip: renders a dashed gray border + 🚫 glyph with
"Not supported by this framework" tooltip; data-status attribute
distinguishes unshipped vs unsupported.
- CoverageBar gains diagonal-stripe gray segment for unsupported.
- StatsBar / AdaptiveStatsBar / CellsView: separate "Unsupported" chip.
- CellMatrix gaps filter excludes unsupported cells (not work to do).
- Tests: cover unsupported in DepthChip, depth-utils, cell-matrix, and
catalog generator metadata/max_depth assertions.
Registers Built-in Agent as a framework in the registry and wires up
a router + sidebar-nav pattern so its content can live at /built-in-agent/*
without needing a dedicated per-framework content tree for every topic.
Content model:
- Root MDX pages (/quickstart, /frontend-tools, /shared-state, etc.) are
the canonical home for framework-agnostic topics. Rendered at
/built-in-agent/<slug> via the existing framework-override mechanism.
- integrations/built-in-agent/*.mdx is the escape hatch for topics that
are genuinely BIA-specific (copilot-runtime, server-tools, mcp-servers,
model-selection, advanced-configuration, custom-agent). The router
falls back to these when no root equivalent exists.
- Root wins when both exist.
Changes:
- shared/manifest.schema.json: add 'built-in' to the category enum.
- shared/packages.json: register built-in-agent slug.
- packages/built-in-agent/manifest.yaml: new. deployed:false (showcase
package TBD in a follow-up), sort_order:0, category:popular so it
appears at the top of the framework dropdown.
- public/logos/built-in-agent.svg: new logo asset (extracted from the
inline CopilotKit mark in brand-nav.tsx).
- shell-docs/src/app/[framework]/[[...slug]]/page.tsx: router gains a
fallback to integrations/<framework>/<slug>.mdx when the root file
doesn't exist. Sidebar nav merges in per-framework overrides as a
labeled section positioned after 'App Control' (mirrors upstream's
integrations/built-in-agent/meta.json ordering).
- shell-docs/src/components/docs-page-view.tsx: new optional
contentSlugPath prop lets the router thread through the override
content path without changing the URL-slug used for breadcrumbs and
active-link detection.
- shell-docs/src/lib/docs-render.tsx: new buildFrameworkOverridesNav
helper that walks integrations/<framework>/* and filters out pages
that already exist at root.
The scrub and #4084 touched the same surface: #4084 re-added an `open:`
generative_ui profile listing `open-gen-ui`/`open-gen-ui-advanced`, and
re-added both features to `constrained-explicit.allowed`. Extending the
branch's scrub to both re-additions keeps the semantic consistent with
the schema (which already dropped `open` from the approaches enum).
- `showcase/shared/constraints.yaml`: drop `open-gen-ui` +
`open-gen-ui-advanced` from `constrained-explicit.allowed`; drop main's
re-added `open:` profile entirely.
- `showcase/packages/langgraph-python/manifest.yaml`: drop the now-orphan
`open-gen-ui` + `open-gen-ui-advanced` feature and demo entries
(validator confirmed they had no allowed approach left).
- Regenerated `showcase/shell/src/data/registry.json` + sibling
`shell-docs`/`shell-dojo` registries and `constraints.json` via
`pnpm --dir showcase/scripts generate-registry`. All 17 integrations
validate.
`feature-registry.json` intentionally still defines both features — the
original scrub commits (2b996c54d, 27f886e59) left it untouched, so the
demo source files on disk also stay. Follow-up deletion if desired is
out of scope for this merge.
Port the 4084 internal-showcase-followups state of the shared showcase
schema to 4085 (no Docker restructure):
- feature-registry.json: new Dev Ex category, category reorder
(Dev Ex → Chat & UI → Platform → Controlled → Declarative → Open →
Operational → Interactivity → Agent State → Multi-Agent → BYOC);
+8 new features (beautiful-chat, cli-start, interrupt-headless,
reasoning-default-render, tool-rendering-reasoning-chain,
open-gen-ui-advanced, declarative-gen-ui-hardcoded,
readonly-state-agent-context); renames (shared-state-write →
shared-state-read-write, shared-state-agent-readonly →
readonly-state-agent-context); removals (shared-state-read,
state-rendering, a2ui-*, shared-state-io, shared-state, readables,
a2a-chat, deep-agents, vnext-chat, byoc-a2ui, byoc-tambo);
gen-ui-agent → kind: testing.
- constraints.yaml: allowlists updated to reference the new IDs.
- manifest.schema.json: `route` is optional; `command` field added for
informational demos (e.g. cli-start).
- All 17 column manifests: shared-state-read removed,
shared-state-write renamed to shared-state-read-write.
- langgraph-python manifest: full 4084 features list + demos entries
with 4085-appropriate highlight paths (src/agents/*.py +
src/app/demos/<cell>/* rather than backend/ + frontend/).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Split generative-ui category into 4 (controlled/declarative/open/
operational), add chat-customization-css + tool-rendering-frontend-tools,
replace old tool-rendering-status/-result IDs with default-catchall /
custom-catchall. Port langgraph-python manifest features + highlight:
paths (column-relative to preserve pre-existing Docker structure).
Update tests for new category/feature counts.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Problem: shell's /code viewer was showing every `.py` file under
`src/agents/` for every demo of a package. Visually contaminating:
opening gen-ui-tool-based (Controlled Gen-UI Display) showed
a2ui_dynamic, a2ui_fixed, mcp_apps_agent, open_gen_ui_agent,
reasoning_agent, interrupt_agent, and tool_rendering_agent in the
file picker even though none of them are relevant to that demo.
Root cause: `bundle-demo-content.ts` ran `discoverBackendFiles()` once
per package and attached the same union of all agent files to every
demo. This was fine when all demos shared one graph, but since we
split demos into dedicated graphs the bundle stopped matching reality.
Fix:
- `manifest.schema.json`: add optional `backend_files` field per demo
(string array, paths relative to the package root).
- `bundle-demo-content.ts`: when `demo.backend_files` is present, bundle
exactly those. Otherwise fall back to the legacy full-package scan
so packages that haven't adopted the field still work as before.
- `langgraph-python/manifest.yaml`: populate `backend_files` for every
demo. Each demo bundles `src/agent_server.py` plus only the agent
file its graph routes to (main.py for shared-graph demos;
reasoning_agent.py / interrupt_agent.py / a2ui_dynamic.py /
a2ui_fixed.py / mcp_apps_agent.py / open_gen_ui_agent.py /
tool_rendering_agent.py for demos with dedicated graphs).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Mike Ryan