The redirect entries are self-describing — source, destination, and
permanent flag say everything the runtime needs. The block comments
were rationale that belongs in commit messages, not in a config file
that future readers scan for shape.
The previous commit renamed the file but didn't add a redirect, so
any open browser tab or external link to /concepts/oss-vs-cloud now
404s — surfacing as a "sidebar disappeared" experience because the
404 page doesn't render the docs shell. Add the 301 redirect alongside
the migrate-to-* and frontend-actions ones.
"Cloud" implied a single deployment shape (managed-only). "Enterprise"
is the accurate name for the layer — same Intelligence Platform runs
hosted at Copilot Cloud or self-hosted via the copilot-intelligence
Helm chart. The page already used "Enterprise" terminology in the
body; this aligns the slug, page title, and meta entry to match.
File renamed via git mv (history preserved). search-index.json paths
update on the next build (gitignored, regenerated).
Replaces the TODO placeholders left by the JTBD restructure with
written explanation-layer content sourced from existing repo material
(learn/architecture, learn/generative-ui, learn/intelligence-platform,
ag-ui/concepts/architecture, premium/overview) and from two CopilotKit
blog posts ("AG-UI Is Redefining the Agent–User Interaction Layer"
and "The Three Types of Generative UI: Static, Declarative and Fully
Generated").
- concepts/architecture.mdx: the three-layer stack (frontend, runtime,
agent), AG-UI as the protocol bridge between runtime and agent, the
request flow at a glance. Reuses the existing architecture-diagram
PNG via ImageZoom and links out to the deeper learn/* coverage.
- concepts/three-types-of-gen-ui.mdx: a freedom-vs-control framing of
Controlled / Declarative / Open-Ended generative UI with one concrete
example per type and explicit "when to pick" guidance. Notes the
alias terminology (Static, Fully Generated) so readers can match the
blog and the learn/ pages. Cross-links to the implementation pages
for each type.
- concepts/oss-vs-cloud.mdx: clear OSS-vs-Enterprise feature split with
a capability-by-capability table, hosted-vs-self-hosted explanation,
and a decision rubric ("if you want CopilotKit to *be* your
conversation persistence layer, that's where Enterprise begins").
All three keep the explanation-layer scope (Diátaxis): they orient
and explain, then point the reader at the canonical detailed pages
for implementation specifics. None of them duplicate how-to content.
The concepts/what-is-copilotkit.mdx placeholder duplicated the
overview rendered at /index.mdx — same intent ("orient the reader"),
same target audience. Keep the index page as the single what-is
entry point and remove the concept-page slot.
The current meta convention pairs a `---X---` section header with a
`...x` spread that resolves to a sub-meta whose `title` is also "X".
buildNavTree emitted both a section node and a group node with the
same title, and the renderers showed each one — so users saw "BUILD
GENERATIVE UI" (section, uppercase tracking-widest) followed by
"Build Generative UI" (group, regular case) for the same content.
The doubling was already on the live site for one section
("Generative UI") and didn't get pushback there, but the JTBD reorg
makes it more visible: every spread-backed section ends up doubled
(Migrate, Other, etc.).
Fix in two halves, kept narrow:
- buildNavTree: when the previously-pushed node is a section header
with the same title that the spread's group would carry, set the
group's title to empty string. The group still wraps its children
for indentation/nesting; only the redundant inner label is dropped.
- All three nav renderers (renderNavItem in docs-page-view.tsx,
OverviewNavItem in app/[[...slug]]/page.tsx, RenderNav in
app/[framework]/[[...slug]]/page.tsx) gain a `{node.title && ...}`
guard so an empty string doesn't render an empty <div>.
Sections without a matching spread (Get Started → index/quickstart/
coding-agents listed inline) and spreads without a preceding section
header (legacy framework-tree work, override merges) are unaffected.
A spread whose sub-meta title differs from the section header (e.g.
section "Observe & Operate" + ...troubleshooting whose title is
"Troubleshooting") still renders both labels, which is correct —
they're meaningfully different and the inner one acts as a
sub-grouping label.
Restructures the top-level sidebar from feature-primitive sections
(Basics / App Control / Backend / Generative UI / Platform / Premium
Features / Troubleshooting) into 9 jobs-to-be-done sections that match
how readers describe what they want to build. Decisions captured in
the IA Restructure plan.
Section structure:
1. Get Started — index, quickstart, coding-agents, + concepts subtree
(placeholders for what-is-copilotkit, architecture,
three-types-of-gen-ui, oss-vs-cloud)
2. Build Chat UIs — prebuilt-components, custom-look-and-feel,
multimodal-attachments
3. Build Generative UI — nested Controlled / Declarative / Open
subgroups (tool-based, tool-rendering, state-rendering, reasoning,
your-components / a2ui + dynamic-schema + fixed-schema / mcp-apps)
4. Give Your App Agent Powers — frontend-tools, shared-state,
multi-agent/subagents, programmatic-control
5. Agents & Backends — built-in-agent (new), copilot-runtime,
custom-agent, ag-ui, runtime-server-adapter
6. Observe & Operate — inspector, vs-code-extension, +
troubleshooting subgroup (event-inspector, hook-explorer,
debug-mode, observability-connectors, common-issues,
error-debugging)
7. Enterprise — premium/overview, premium/observability,
premium/self-hosting, threads (merged from former Threads section
per product call: threads + persistence are part of Enterprise)
8. Migrate — v2, 1.10.X, 1.8.2 (moved out of Troubleshooting and
renamed to drop the redundant 'migrate-to-' prefix)
9. Other — contributing, telemetry (unchanged)
Reference stays as a separate root-true tree, not surfaced through the
top-level meta. Its v1/v2 treatment is a follow-up decision.
Page moves and new files:
- Migration guides moved from troubleshooting/migrate-to-{v2,1.10.X,
1.8.2}.mdx to migrate/{v2,1.10.X,1.8.2}.mdx with 301 redirects from
the old URLs in next.config.ts. Migrate gets its own first-class
section with a lucide/RefreshCw icon — separate from
Troubleshooting per IA-analysis pillar ("I'm upgrading deliberately"
≠ "something broke").
- 4 concept placeholders + index under content/docs/concepts/. Each
has frontmatter (title, description, icon, doc_type: explanation)
and a TODO body referencing where the content will come from
(existing repo material + blog posts). Slot exists; content
backfills later.
- New built-in-agent.mdx at root — 1-page summary that places BIA in
Agents & Backends as a peer to copilot-runtime / custom-agent / etc,
with a link out to the full BIA-scoped docs at /built-in-agent.
Other meta moves:
- programmatic-control: Basics → Give Your App Agent Powers
- inspector: Basics → Observe & Operate
- vs-code-extension: Platform → Observe & Operate
- multimodal-attachments: Platform → Build Chat UIs
- runtime-server-adapter: Platform → Agents & Backends
- The 3 migration pages: Troubleshooting → Migrate (with file moves)
Removed dead code: the `...unselected` line in top-level meta.json
was a no-op (unselected/meta.json has `root: true` so the spread
produced nothing). Stripped during the rewrite.
Multiple new visible labels are intentional. The renderer renders
sections (uppercase tracking-widest) and groups (medium-weight regular
case) at the same level when a section spreads a sub-meta with a
matching title — same pattern that's been live for 'Generative UI'
through every prior PR. The Build Generative UI nesting (Controlled /
Declarative / Open) is a deliberate three-types-of-gen-UI subgrouping
inside the section, surfaced via subsection headers in
generative-ui/meta.json's pages array.
## Summary
- Fix probe run history always returning empty — the invoker writes PB
rows with bare `cfg.id` (e.g. `e2e-deep`) but the HTTP handler queried
with the scheduler entry ID including the `probe:` prefix (e.g.
`probe:e2e-deep`), so they never matched
## Test plan
- [x] 1320 tests pass
- [x] Typecheck clean
- [ ] CI green
- [ ] After deploy, click probe:e2e-deep row on dashboard and confirm
"Recent Runs" populates
The invoker writes PB rows with bare cfg.id (e.g. 'e2e-deep') but
the HTTP handler passed the scheduler entry id with 'probe:' prefix
(e.g. 'probe:e2e-deep') to writer.recent(). The IDs never matched,
so run history always returned empty.
Completes the declarative-gen-ui cell for mastra (5/5 regions). The
runtime-inject-tool snippet teaches the TS-runtime injectA2UITool flag —
mastra's actual route bundles generateA2uiTool into weatherAgent so it
doesn't follow this pattern, but the docs page is teaching the runtime
feature itself, so a docs-only sibling file matches the established
pattern (see chat-component.snippet.tsx in agentic-chat).
Adds the @region[name] / @endregion[name] markers the shell-docs <Snippet>
mechanism needs to resolve mastra-scoped code blocks. Brings 10 cells from
"missing snippet" warnings to clean rendered code in the docs.
Two patterns:
1. In-place markers (12 of the 14 file edits) — wrap existing demo source
where it already reads as a clean teaching example. Comment-only,
stripped from rendered output, zero runtime change.
2. Sibling <region>.snippet.tsx files (2 new files) — for cases where
the production demo carries QA hooks (frontend tools, render tools,
agent context) that aren't relevant to the docs page being taught.
Lives in the demo folder so the bundler picks it up; not imported,
not rendered. Used for agentic-chat/chat-component (mastra Chat is
QA-laden) and tool-rendering/render-flight-tool + catchall-renderer
(mastra demo only renders weather, not flights or catchall).
Cells advanced to ready: prebuilt-popup, prebuilt-sidebar, frontend-tools,
chat-customization-css, agentic-chat-reasoning, chat-slots, agentic-chat,
tool-rendering, headless-complete, plus partial coverage on declarative-gen-ui
(provider-a2ui-prop only; runtime-inject-tool is missing on every framework
and needs a cross-cutting authoring round on langgraph-python first).
Out of scope: a2ui-fixed-schema and the runtime-inject-tool region on
declarative-gen-ui (cross-cutting — reference framework lacks them too);
shared-state-*, subagents, gen-ui-*, mcp-apps, open-gen-ui*, interrupt-headless
(stub or no-folder on mastra — engineering work).
Documents the D5 e2e-deep Chromium memory envelope (4 services x 2
features = 8 concurrent contexts, ~2.4GB peak) and the two tuning
knobs operators should adjust if OOM occurs.
Semaphore unit tests verify the counting semaphore gates concurrent
access correctly at limit=1, limit=2, and limit>=N. Feature parallelism
test confirms FEATURE_CONCURRENCY=2 produces peak context count of 2
when 4 features run. Feature-type filtering tests cover the driver-level
ctx.featureTypes filter (filtered-by-trigger note, all-filtered short-
circuit) and the HTTP handler validation (empty array, empty strings,
non-array, combined slugs+featureTypes, rate-limit non-consumption on
400). Graceful degradation test verifies correct aggregate results
regardless of concurrency level.
Exports Semaphore class and FEATURE_CONCURRENCY constant from
e2e-deep.ts for direct unit testing.
When ctx.featureTypes is set from the trigger layer, partition runnable
features into kept and filtered sets before the execution loop begins.
Filtered features are recorded as skipped with a "filtered-by-trigger"
note so dashboards can distinguish trigger-scoped runs from no-script
skips. Logging emits the filter and excluded count when active.
Accept optional featureTypes in the trigger request body filter. Validates
that featureTypes is a non-empty array of non-empty strings when present,
returning 400 with a descriptive error otherwise. Forwards the validated
featureTypes into TriggerOptions alongside existing slug filtering.
Replace the sequential for-loop over runnable features with a
semaphore-gated Promise.allSettled pool capped at
FEATURE_CONCURRENCY=2. Each feature already creates its own
independent browser context, so there is no shared mutable state
between concurrent runs. Results are collected from settled promises
to preserve input ordering. Setting FEATURE_CONCURRENCY=1 degrades
to identical sequential behaviour.
Add optional featureTypes?: string[] to ProbeContext, TriggerOptions,
and InvokerTriggerOptions. The invoker extracts the field from trigger
opts and forwards it into the ProbeContext passed to each driver, so
drivers like e2e-deep can restrict their run scope to specific feature
types without changes to the scheduler or HTTP layer.
1. Add missing @json-render/core and @json-render/react deps to
google-adk package.json (Docker build failed on byoc-json-render
demo imports)
2. Update catalog test expectations to match actual generated counts
(wired 482, crewai-crews 28, LGP 37 wired + 2 unshipped)
3. Regenerate google-adk starter from template to eliminate drift
detected by the starter consistency check
Rewrite starter route.ts to use HttpAgent (matching packages pattern),
fix default port to 8123, add full 37-agent list including sample_agent,
add missing @ag-ui/client dependency, register sample_agent in registry.
Update open-gen-ui agent instructions to emit HTML directly instead
of fenced blocks (the runtime's generateSandboxedUi tool handles
rendering). Tighten sandbox evaluateExpression regex to reject **
exponentiation. Fix ternary operator precedence in 3 agent files
where string concatenation bound tighter than the conditional.
Remove stack trace leaks from error responses, replace @ts-ignore
with @ts-expect-error, hoist CopilotRuntime to module scope, and
add [[...slug]] catch-all for the V2 auth endpoint so sub-route
requests don't 404.
Round 5 review surfaced a fragility in the empty-write guard. The
`if not new_text` short-circuit added in Round 4 correctly avoids
clobbering the LlmAgent static `instruction=` field when there's
nothing to inject — but if a prior callback DID embed a block in the
existing Content and the user has since cleared state, the early
return leaves the stale block in place because we never write the
stripped result back.
In practice this is unreachable: `_INSTRUCTION` is non-empty for all
three agents, so `original_text` after stripping always retains at
least the static instruction. But the explicit `stripped_prior_block`
flag makes the invariant honest if anyone ever wires up an LlmAgent
with an empty `instruction=` and removes the implicit dependency on
the static instruction being non-empty.
eslint-plugin-unicorn no-useless-fallback-in-spread — spreading
undefined into an object literal is a no-op, so '?? {}' is redundant.
Functionally identical, silences the lint warning.
Two related issues surfaced in Round 4 review of the ADK showcase:
1. The before-model callbacks in agent_config_agent,
readonly_state_agent_context_agent, and shared_state_read_write_agent
guarded the empty-write branch with `if not new_text and original is
None`. That missed the case where `original` is a non-None Content
with empty text — possible after stripping a prior block that was
the entire Content. In that branch the callback wrote
Content(text=""), clobbering the LlmAgent's static `instruction=`.
Tightened the guard to `if not new_text: return None`.
2. The shared-state-read-write seed effect spread the observed agent
state but unconditionally assigned `notes: []`, wiping any
backend-persisted notes when the user landed without persisted
preferences. Falls back to `agentState?.notes ?? []` instead.
Round 3 confirmation found bugs Round 2's fixes left behind in the same
files. All fixes target subject-scoped + load-bearing concerns.
bucket (a) findings:
A1 (strip-prior-block content loss): all three before-model-callback
agents (\`agent_config_agent\`, \`readonly_state_agent_context_agent\`,
\`shared_state_read_write_agent\`) sliced
\`original_text[end_idx + len(END_MARKER):]\` to remove the prior
injected block. That dropped content from index 0 to sig_idx as well —
fine for the steady-state pattern where our block is at position 0,
but if any other middleware ever prepends content to system_instruction
between turns, that prefix would be silently lost. Splice instead:
\`original_text[:sig_idx] + original_text[end_idx + len(END_MARKER):]\`.
A2 (empty-block + empty-original still rewrites system_instruction):
when both \`block\` is None and \`original\` is None, the callbacks were
still writing \`Content(role="system", parts=[Part(text="")])\`,
overwriting whatever the LlmAgent's \`instruction=\` field would have
contributed. Added an early return for that case so the static
instruction passes through.
A3 (sub-agent error message exposes raw exception text):
\`_invoke_sub_agent\` was raising
\`_SubAgentError(f"sub-agent call failed: {exc.__class__.__name__}: {exc}")\`.
\`{exc}\` for genai HTTP errors can include URLs, request IDs, partial
credentials, and quota details. The error string lands in
\`state["delegations"][i].result\` and ships to the public Railway
deploy. Sanitized to surface only \`exc.__class__.__name__\` to clients;
\`logger.exception\` keeps the full trace + str(exc) server-side.
A4 (agent.setState seed/handler effects clobber unrelated state keys):
\`agent.setState({ config: INITIAL_CONFIG })\` and the matching prefs
seed/handlers replaced the whole state object rather than merging. If
the runtime adds any other keys (e.g. \`copilotkit\` for the read-only
context middleware, future framework additions), they were wiped on
every config write. Now spread the observed state on every write.
A5 (\`_build_prefs_block\` missing the empty-recognized-keys guard): a
truthy prefs dict containing only unrecognized keys (schema drift /
forward-extension UI prop) would still emit a block consisting only of
\`[SIG, "Tailor every response to these preferences. ADDR_USER_BY_NAME"]\`,
i.e. directives without directives. Added the same
\`if len(lines) == 1: return None\` guard already present in
\`agent_config_agent._format_config\` and
\`readonly_state_agent_context_agent._format_context\`.
Bucket (b) defensive items applied:
- subagents \`_invoke_sub_agent\` parts extraction: dropped the redundant
\`if content is not None\` ternary; \`getattr(None, "parts", None)\`
already returns the default.
Starter regenerated.
Call-site enumeration:
- splice path inside \`_inject_config\`/\`_inject_context\`/
\`_inject_preferences\`: signature unchanged; only callers are the
matching LlmAgent before_model_callback bindings.
- \`_SubAgentError\` constructor message format changed (still str
argument): consumers stringify it via str(exc); behaviour unchanged
apart from the redacted exception body.
- \`agent.setState\` payloads in agent-config + shared-state-read-write
pages: consumed only by the matching runtime route per page; the
spread shape is a superset of the prior shape, so backend callbacks
see the same fields plus any pre-existing keys (which they already
read defensively).
- \`_build_prefs_block\` early-return: only consumer is
\`_inject_preferences\` in the same module; new return path is None,
same as the existing \`not prefs\` early return.
Round 2 (confirmation) surfaced bugs in code my Round 1 fixes touched.
bucket (a) findings:
- subagents_agent._update_delegation: dropped the synthetic
\`sub_agent: "unknown"\` fallback I added in Round 1. The frontend's
\`Delegation.sub_agent\` union is
\`research_agent | writing_agent | critique_agent\`; an "unknown" value
fell through SUB_AGENT_BADGE_CLASS / SUB_AGENT_LABEL maps and rendered
as \`undefined\` text + className. Now we log loudly and skip — no row
beats a malformed row.
- subagents_agent._invoke_sub_agent: cleaned up the
\`getattr(content, "parts", None) or [] if content is not None else []\`
ternary. \`getattr(None, ...)\` already returns the default, so the
outer conditional was dead.
- agent_config_agent._format_config: added \`if len(lines) == 1: return None\`
guard before appending CONFIG_END_MARKER. A truthy config dict with no
recognized keys (schema drift / future-extension forwardedProps) was
emitting a meaningless [SIGNATURE, END_MARKER] block telling the LLM
to "Honour every directive above" with zero directives. Mirrors the
same guard in readonly_state_agent_context_agent._format_context.
- delegation-log.tsx: added STATUS_BADGE_CLASS + STATUS_LABEL maps and
a status-derived border-color so running/completed/failed entries are
visually distinguishable. Without this, my Round 1 backend fix that
actually emits all three states had no UI signal — every entry was
the same muted gray. Now: amber spinner + "running…" while the
sub-agent works, emerald on completion, red on failure.
- hitl-in-app/page.tsx: added an unmount cleanup that rejects every
still-pending approval (with reason "user navigated away before
responding") so the agent's tool-call promises never orphan when
the user leaves the page mid-approval. Also added \`key={head.id}\`
on ApprovalDialog so any future local state in the dialog component
is per-request rather than leaking from one approval to the next as
the head rotates.
- tool-rendering-custom-catchall: aligned the renderer's status type
with what the runtime + page actually emit. The runtime's
DefaultRenderProps status enum is
\`"inProgress" | "executing" | "complete"\` and the page collapses both
pre-completion variants to "executing"; there is no "incomplete"
state today. The renderer's \`"incomplete"\` branch was unreachable
dead code from a copy-paste of an older type. Narrowed the prop type
to \`"executing" | "complete"\` and dropped the dead branch.
- manifest.yaml highlight arrays: 7 demos with dedicated runtime
routes (a2ui-fixed-schema, declarative-gen-ui, byoc-json-render,
byoc-hashbrown, auth, open-gen-ui, open-gen-ui-advanced) were
pointing at the unified \`src/app/api/copilotkit/route.ts\` instead
of their own dedicated route file. Documentation drift the showcase
tooling uses to render source listings — pointed each at its real
route. Also added \`src/app/demos/auth/demo-token.ts\` to the auth
highlight list so the bundled demo-token note is visible alongside
the page.
bucket (b) cheap items applied:
- AgentSpec.predict_state: \`Iterable\` → \`Sequence\`. A one-shot
generator passed by mistake would empty after the first request;
Sequence forces a re-iterable container. Module-level lists already
satisfy this contract.
Starter regenerated to keep drift-check green.
Call-site enumeration:
- \`STATUS_BADGE_CLASS\`, \`STATUS_LABEL\`, \`ENTRY_BORDER_BY_STATUS\`
(new): private to \`delegation-log.tsx\`.
- \`pendingQueueRef\` (new): private to hitl-in-app/page.tsx unmount cleanup.
- \`_update_delegation\` signature unchanged; only the missing-entry
branch behaviour changed (no longer appends).
- \`AgentSpec.predict_state\` widened constraint
(Iterable→Sequence): only consumed in agent_server.py's
ADKAgent construction; passing a list still satisfies Sequence.
- CustomCatchallRendererProps.status narrowed
(executing|complete|incomplete → executing|complete): only
consumer is the page in the same demo folder; it now passes a
matching union.
CR Round 1 remaining bucket (a) findings + cheap (b) items:
A1 (streaming claim alignment): \`shared_state_streaming_agent.py\` no
longer carries an empty \`GenerateContentConfig()\` with comments that
claimed it enabled per-token streaming. Per-token streaming is driven
by (i) \`PredictStateMapping(stream_tool_call=True)\` set on the
ADKAgent middleware and (ii) the new
\`streaming_function_call_arguments=True\` kwarg added to the AgentSpec
+ agent_server.py wiring. The kwarg degrades gracefully on google-adk
< 1.24.0 with a UserWarning per the upstream contract.
A8 (useEffect race): both \`agent-config/page.tsx\` and
\`shared-state-read-write/page.tsx\` previously seeded INITIAL_* with
empty deps on mount, which fired BEFORE the runtime hydrated agent.state
on a page reload — overwriting backend-persisted config/preferences with
defaults. Replaced with a \`seededRef.current\` flag that gates the seed
to a single emission AFTER agent.state has been observed at least once.
Effect now correctly lists \`agent\` + \`agentState\` deps (no eslint
disable).
A9 (notes-card stable key): \`shared-state-read-write/notes-card.tsx\`
\`key={i}\` for plain-string lists used pure positional identity.
Replaced with \`key={i}::\${note}\` so DOM identity tracks both
position and content — agent rewrites of the notes list no longer
attach scroll/selection state to the wrong row.
A10 (hitl-in-app concurrent approvals): replaced
\`useState<ApprovalRequest | null>\` with a queue. Gemini's parallel
tool-call paths can fire \`request_approval\` more than once before the
first resolves; the previous single-slot state orphaned the first
promise (the agent waited forever). Queue head renders, every approval
resolves in arrival order, removal is filter-by-id-safe under
concurrent resolves.
A13 (OGUI runtime config): \`copilotkit-ogui/route.ts\` was missing
\`openGenerativeUI: { agents: [...] }\` on the CopilotRuntime. Without
it the OpenGenerativeUIMiddleware never engaged, so the
\`generateSandboxedUi\` tool calls from \`open_gen_ui\` /
\`open_gen_ui_advanced\` never converted to activity events and the
sandboxed iframe stayed empty. Verified the langgraph-python sibling
configures it the same way.
A14 (booked_schema parity): every sibling integration loads
\`BOOKED_SCHEMA = a2ui.load_schema(...)\` for parity even though the
A2UI Python SDK does not yet accept \`action_handlers\` for swap-on-
click; google-adk's \`a2ui_fixed_agent.py\` was the only package to
ship the JSON without loading it. Added the load + manifest highlight
entries.
A15 (handleClearNotes stale closure): same file as A9. Both handlers
now read latest agent state via the closure-fresh \`agentState\`
rather than the destructured \`preferences\` / \`notes\` snapshots that
went stale under rapid concurrent edits.
Bucket (b) cheap items applied:
- \`agent_server.py\`: \`reload=True\` → env-gated via UVICORN_RELOAD,
so production runs aren't burning CPU on file-watching.
- \`agent_server.py\` /agents/state docstring: now explicitly names the
FIRST registered agent (\`_simple_chat\`-shared demos work; bespoke-
LlmAgent demos store sessions in their own ADKAgent's service that
/agents/state doesn't reach — STATE_DELTA via useAgent still works).
- \`registry.py\`: stale "Already-implemented demos" header dropped;
\`_SIMPLE_CHAT_INSTRUCTION\` rewritten to be tool-agnostic so the
hint matches every demo that shares this agent (frontend-tools,
headless-simple's \`show_card\`, etc.).
- \`tool-rendering-custom-catchall/page.tsx\`: \`: any\` cast on render
args replaced with inferred types + an explicit status-narrow at the
call site.
- \`voice/page.tsx\`: empty \`input={{}}\` prop removed — was overriding
CopilotChat's default input slot with no override at all.
- \`byoc-json-render\` page+route: agent name renamed to
\`byoc-json-render-demo\` (kebab + \`-demo\` suffix) to match
sibling \`byoc-hashbrown-demo\` / \`a2ui-fixed-schema\` /
\`auth-demo\` convention.
Starter regenerated to keep drift-check green.
Call-site enumeration:
- \`AgentSpec.streaming_function_call_arguments\` (new field): only
consumed in agent_server.py's \`ADKAgent(...)\` construction.
- \`SHARED_STATE_STREAMING_PREDICT_STATE\`: re-exported, signature
unchanged.
- \`AGENT_REGISTRY\` shared-state-streaming entry now passes
streaming_function_call_arguments=True; no other callers.
- \`byoc-json-render-demo\` agent string: only consumed in the
matching dedicated route + the corresponding page.tsx; both
updated together.
CR Round 1 bucket (a) finding A12: doc-comments referenced files and
wiring patterns that don't match the actual code in this package.
- a2ui-fixed-schema/page.tsx: \`src/agents/a2ui_fixed.py\` →
\`src/agents/a2ui_fixed_agent.py\` (actual filename)
- declarative-gen-ui/page.tsx: \`src/agents/a2ui_dynamic.py\` →
\`src/agents/declarative_gen_ui_agent.py, which re-exports the
generate_a2ui tool defined in src/agents/main.py\`
- auth/demo-token.ts: header referenced \`use-demo-auth.ts\` (no such
file in this package); now points at \`./page.tsx\` and adds a
reminder that the constant ships into the browser bundle.
- open-gen-ui/page.tsx: rewrote to describe the actual two-pronged
wiring — \`openGenerativeUI\` on the runtime AND on the provider —
rather than just naming the runtime; the prior single-source claim
obscured the activity-renderer activation that lives on \`<CopilotKit>\`.
- byoc-hashbrown/page.tsx: removed \"Wave 4a\" internal sequencing
label; \"langgraph-python agent\" → \"Google ADK byoc_agent\".
- byoc-json-render/page.tsx: \"the LangGraph agent\" → \"the Google
ADK byoc_agent\"; \"Wave 4a's hashbrown demo\" → \"the
byoc-hashbrown demo\".
Comments-only change. No behavioural impact.
Call-site enumeration: doc-comments are leaf changes; no symbols
added, removed, or renamed; no call sites to enumerate.
CR Round 1 bucket (a) findings A6, A7, A11:
A6 (silent no-op on malformed state): all three before-model-callback
agents (agent_config, readonly_state_agent_context, shared_state_read_write)
imported `logging.getLogger(__name__)` but never called the logger when
the frontend sent a non-dict / non-list payload. Schema drift was
indistinguishable from "user hasn't set anything yet". Now log
\`logger.warning(...)\` with the observed type so the regression surfaces
server-side.
A7 (readonly-context: early returns leave stale prior block): when
\`state["copilotkit"]\` or \`state["copilotkit"]["context"]\` was the
wrong shape, \`_inject_context\` returned without reaching the
strip-prior-block path — any context block injected on a previous turn
would stay embedded in \`system_instruction\` indefinitely. Now coerce
malformed state to \`raw_entries = []\` so the strip path always runs.
A11 (agent_config docstring stale): top-of-file docstring listed only
\`tone/expertise/response_length\` but the impl + frontend also handle
\`language\`. Updated.
Also extracted the trailing-sentence end markers into module-level
constants (\`CONFIG_END_MARKER\`, \`CONTEXT_END_MARKER\`,
\`PREFS_END_MARKER\`) so the strip logic and the \`_format_*\` builders
can't drift apart from a one-place edit. Added a warning log when a
signature is present but the end marker is missing — previously the
strip silently no-op'd and prior blocks would stack on subsequent turns.
Call-site enumeration:
- \`CONFIG_END_MARKER\`, \`CONTEXT_END_MARKER\`, \`PREFS_END_MARKER\`
(new): private to their respective modules; only consumed by the
builder + strip pair within each file.
- \`_format_config\`, \`_format_context\`, \`_build_prefs_block\` (logic
changed): private to their modules; unchanged signature.
- \`_inject_config\`, \`_inject_context\`, \`_inject_preferences\` (logic
changed): wired only into LlmAgent's \`before_model_callback\`;
signature unchanged.
CR Round 1 bucket (a) findings A2-A5:
A2 (errors recorded as completed): \`_record_delegation\` always set
\`status: "completed"\` even when \`_invoke_sub_agent\` returned a
\`(sub-agent error: …)\` string. The frontend's "failed" badge style was
defined but never reached. Replaced with a typed \`_SubAgentError\` plus
a \`_delegate\` flow that appends a "running" entry, invokes, then
flips to "completed"/"failed" with the actual error message.
A3 (never emits running): the Delegation type union has
\`"running"|"completed"|"failed"\` but only "completed" was ever written.
Now appended at delegation start; demo's "live delegation log" claim is
truthful.
A4 (AttributeError on safety-blocked responses):
\`getattr(candidates[0].content, "parts", None)\` directly accessed
\`.content\` — None content (safety-blocked, empty parts) raises
AttributeError on the inner getattr. Now guards content via getattr
first.
A5 (exception list too narrow): \`except (genai_errors.APIError,
ValueError)\` let httpx.ConnectError, asyncio.TimeoutError, RuntimeError
propagate up and crash the supervisor's tool turn. Catching the broad
\`Exception\` is appropriate here because the user-visible surface is a
structured \`{status: "failed", error}\` dict — server-side traceback is
preserved via \`raise … from exc\`.
Tool return shape changed from \`{"result": str}\` to
\`{"status": "completed"|"failed", result?, error?}\`. Supervisor
instruction updated to describe the new shape so the LLM can handle
sub-agent failures explicitly instead of fabricating a reply.
Call-site enumeration:
- \`_SubAgentError\`, \`_append_delegation\`, \`_update_delegation\`,
\`_delegate\`: new private helpers, no external callers
- \`_record_delegation\` (removed): was private, no callers outside this
module
- \`research_agent\`/\`writing_agent\`/\`critique_agent\` (return shape):
only consumed by the LLM via tool-calling. Frontend reads
\`state["delegations"]\` directly; its Delegation type already has
the full status union.
- \`subagents_root_agent\` re-export: unchanged; registry import still
resolves.
Without per-feature override entries, the dashboard's DocsRow falls
through to the global feature probe in shared/feature-registry.json.
For features whose canonical docs path doesn't exist on
docs.copilotkit.ai (e.g. an ADK-scoped page for shared-state-streaming
where only the langgraph-* equivalent is published) the probe returned
notfound and the docs/shell columns rendered as red ✗.
Mirror the pre-existing 8 entries' pattern: each new feature gets either
\`og_docs_url\` pointing at the real /adk/... page where one exists, or
\`og_docs_url: null\` for features without a canonical ADK page (which
the cell renders as an honest gray "opt-out" dot rather than red ✗).
\`shell_docs_path\` stays null for every feature — there's no
google-adk-scoped docs tree under shell-docs (PR #4085).
\`validate-fixture-tool-surface.ts\` resolves a demo's backend tool
surface by file name (\`<agentId>.py\` or \`<agentId>_agent.py\`); the
prior plural \`tool_rendering_agents.py\` matched no agentId, so the four
tool-rendering variants had empty tool surfaces and the validator flagged
"weather" fixture drift. Split into per-variant files
(tool_rendering_agent.py, tool_rendering_default_catchall_agent.py,
tool_rendering_custom_catchall_agent.py,
tool_rendering_reasoning_chain_agent.py) that share a new
tool_rendering_common.py for the get_weather / search_flights /
query_data implementations and the system prompt. \`tools=[...]\` is now
a literal at module scope per file so the validator's regex picks it up.
Verified locally: \`pnpm exec tsx validate-fixture-tool-surface.ts\` →
65 fixtures × 534 demos, no drift.
\`validate-fixture-tool-surface.ts\` parses backend tool surfaces with
\`/tools\s*=\s*\[/\` — that regex matches \`tools=[...]\` keyword-arg
syntax, not \`"tools": [...]\` dict-key syntax. The previous \`_build\`
helper passed tools through a kwargs dict, leaving the four
tool-rendering variants with empty tool surfaces and triggering aimock
fixture drift on the "weather in Tokyo" suggestion. Inline the four
constructors so \`tools=[get_weather, search_flights, query_data]\` is
visible to the regex.
The Windows-generated starter wrote \`from .tools import\` for files inside
agent/tools/, but the Linux generator emits \`from . import\` because
\`filePath.includes("/tools/")\` only matches forward-slash paths
(generate-starters.ts:494). Match the Linux output so the drift check
passes.
Pre-existing drift on main: showcase/packages/crewai-crews/src/agent_server.py
was migrated from BaseHTTPMiddleware to a raw ASGI splice (commits 72c79bf99,
6b1ccfa86, ecbc76872, f16ea4d96) without regenerating the starter, so the
drift check was failing on every PR including this one. Re-emit via
\`pnpm exec tsx showcase/scripts/generate-starters.ts --slug crewai-crews\`.
`generate-starters.ts` regenerates each starter from its source package; the
prior commits added 18 new agent modules + refactored agent_server.py in the
google-adk package, so the starter needed re-emission. Generated via
`pnpm exec tsx showcase/scripts/generate-starters.ts --slug google-adk`.
Fixes drift-check failure on this branch.
Backend: refactor src/agent_server.py from a single shared LlmAgent at /
to one ADKAgent per demo at /<agent_name>, driven by a new
src/agents/registry.py source-of-truth (with AgentSpec dataclass for
predict_state / emit_messages_snapshot kwargs). Adds 18 per-demo agent
modules covering reasoning, tool-rendering, HITL, shared-state,
multi-agent, A2UI dynamic + fixed-schema, BYOC, open-gen-ui, and others.
Frontend: src/app/api/copilotkit/route.ts now maps each agent name to its
matching backend path. Adds 6 dedicated runtime routes for demos that
need bespoke runtime config: copilotkit-auth (V2 createCopilotRuntimeHandler
with onRequest 401 gate), copilotkit-declarative-gen-ui and
copilotkit-a2ui-fixed-schema (a2ui.injectA2UITool: false), plus
copilotkit-byoc-{hashbrown,json-render} and copilotkit-ogui (shared by
open-gen-ui + advanced).
Manifest: declares 35 features (was 8). Dashboard wired count for
google-adk goes from 8/39 to 35/39, parity_tier minimal -> partial.
Reference (langgraph-python) is at 38/39.
Skipped (intentional): gen-ui-interrupt and interrupt-headless rely on
LangGraph's interrupt() primitive with no direct ADK equivalent;
mcp-apps left for follow-up.
## Summary
- Bundle all 9 D5 (e2e-deep) fixture files into
`showcase/aimock/d5-all.json` so aimock loads them at boot via GitHub
raw URL. **Root cause of 93/158 D5 red cells**: the D5 fixtures in
`showcase/ops/fixtures/d5/` were never loaded into aimock — probes hit
real LLMs producing non-deterministic responses that fail strict
assertions.
- Add new `hitl-steps` D5 feature type + probe script for the
`/demos/hitl` route, which renders a step-selection UI
(`StepsFeedback`), not a time-picker. The previous mapping (`hitl →
hitl-text-input`) drove the wrong interaction against the wrong page.
- Update `RAILWAY.md` with the new fixture URL and updated
`startCommand` (d5-all.json loads before feature-parity.json for match
precedence).
## Post-merge deploy step
After merge, the Railway `startCommand` for `showcase-aimock` must be
updated to include the new `--fixtures` URL:
```sh
node /app/dist/cli.js \
--proxy-only \
--provider-openai https://api.openai.com \
--provider-anthropic https://api.anthropic.com \
--provider-gemini https://generativelanguage.googleapis.com \
--fixtures https://raw.githubusercontent.com/CopilotKit/CopilotKit/main/showcase/aimock/d5-all.json \
--fixtures https://raw.githubusercontent.com/CopilotKit/CopilotKit/main/showcase/aimock/smoke.json \
--fixtures https://raw.githubusercontent.com/CopilotKit/CopilotKit/main/showcase/aimock/feature-parity.json \
--validate-on-load \
--host 0.0.0.0 \
--port 4010
```
Then restart the aimock service to pick up the new fixtures.
## Test plan
- [x] 100/100 D5 tests pass (11 test files)
- [x] New hitl-steps tests: 7/7 pass
- [x] Existing hitl-text-input tests: no regression (10/10)
- [x] d5-all.json validated: 23 fixtures, correct structure
- [ ] After deploy: trigger D5 probe cycle and verify red count drops
from 93 to near-zero
Sam Julien