## Mastra Partner Refresh — showcase finalization (OSS-381)
Bumps the showcase Mastra integration onto the **v1 bridge alpha** and
flips the
features it unblocks out of `not_supported`. Opened for CI to run the
D6/e2e
suite (local Docker daemon is wedged in the authoring env — see notes).
### Landed
- **OSS-382 (gate):** `@ag-ui/mastra` `0.2.1-beta.2` →
**`1.1.0-alpha.0`**.
- Alpha verified to ship all features (grep on dist):
`emitInterruptOutcome`,
`STATE_DELTA`, `observationalMemory`, `background-task`,
`tracingOptions`,
`getA2UITools`/recovery. Peers satisfied (`@mastra/core` 1.41,
`client-js`
1.23.2, runtime 1.61.2).
- `next build` passes (40 routes). Unit tests **identical to the beta.2
baseline** (13 pre-existing failures in `route.test.ts`'s error-path
mocks,
unrelated to the bump — proven by a stash+reinstall A/B).
- **OSS-384 / OSS-423:** moved into `features` (demos + e2e + aimock
fixtures
were already wired, gated on this release):
`agentic-chat-reasoning`, `reasoning-default-render`,
`tool-rendering-reasoning-chain`, `shared-state-streaming`. Added the
missing
`reasoning-default` / `reasoning-custom` manifest demo entries.
- **Parity:** `not_supported_features` now holds only `gen-ui-interrupt`
+
`interrupt-headless`, matching the **langgraph-python gold standard**,
which
quarantines the same two cells on an upstream `@copilotkit/react-core`
v2
resume-path hook bug (published-package fix, out of scope). The native
interrupt + RUN_FINISHED-outcome path ships in the bridge; the showcase
cell
is blocked by the same upstream bug, not the bridge.
- **OSS-424:** execution-tracing note (`tracingOptions` in / `traceId`
on
`RUN_FINISHED.result` out) added to the Mastra Copilot Runtime doc.
- **OSS-425:** GenUI `generative_ui` spectrum already at parity with
gold
(`constrained-explicit`, `a2ui-fixed-schema`, `a2ui-dynamic-schema`).
### Not in this PR (scoped, blocked, or pending)
- **OSS-422 a2ui-recovery**, **OSS-426 background-agents**, **OSS-427
observational-memory** — new demo cells. Reference material + build
plans
ready. OM additionally needs `@mastra/memory` ≥1.21.2 (repo pins
`1.0.1-alpha.1`; the on-stream async-buffering path won't fire below
that).
- **OSS-91 browser-use** — Mastra-only, non-deterministic (no clean
aimock
replay), needs a Browserbase key not present in the env. Blocked.
- **OSS-392 input.context** — owner exception; only if langgraph
showcases it.
### Verification note
Local D6 could not be run: the Docker daemon's container-creation path
is wedged
in this environment (a trivial `hello-world` create hangs), and
unwedging needs a
Docker Desktop restart that would destroy a concurrent session's running
stack.
Relying on CI for D6/e2e. Everything above is build-level verified +
committed.
generate-registry.ts imports the catalog cross-join/flatten fold from
../harness/src/shared/catalog/catalog-flatten.ts, which does
`import yaml from "js-yaml"`. The generator's build/test environments did
not stage that file (or its module-resolution scope), so the fold could
not resolve.
- Dockerfiles (shell, shell-dashboard, shell-docs, shell-dojo): COPY the
shared catalog source + harness/package.json (its `"type":"module"` is
required so catalog-flatten resolves as ESM and its named exports bind)
and provide a node_modules for js-yaml resolution.
- generate-registry-pattern.test.ts (makeHarness): stage catalog-flatten.ts
and harness/package.json at the exact relative path the generator
resolves, and symlink the scripts node_modules onto the harness tree so
the ESM `import yaml from "js-yaml"` resolves.
- js-yaml + @types/js-yaml added to showcase/scripts (package.json and the
npm package-lock.json), and the root pnpm-lock.yaml regenerated to add
the matching importer entries for showcase/scripts (js-yaml >=4.1.1 via
the root override, @types/js-yaml ^4.0.9) so `pnpm install
--frozen-lockfile` stays in sync.
## What & why
Three independent documentation-accuracy fixes, batched into one PR.
### 1. Dead spec links + gen-ui page gaps (Closes#3975)
`generative-ui-specs-overview.mdx` (rendered at
`/whats-new/generative-ui-spec-support`) linked to the retired
`/generative-ui/specs/<spec>` subgroup. Repointed to canonical
destinations and added the frameworks list the issue asked for.
**Verified live (HTTP status against docs.copilotkit.ai):**
| Link | Before | After |
| --- | --- | --- |
| A2UI | `/generative-ui/specs/a2ui` (301 hop) | `/generative-ui/a2ui` →
**200** |
| MCP Apps | `/generative-ui/specs/mcp-apps` (301 hop) |
`/generative-ui/mcp-apps` → **200** |
| Open Generative UI (new) | — | `/generative-ui/open-generative-ui` →
**200** |
- **Supported Frameworks** list added — all 12 `/<slug>/quickstart`
targets return **200** live (LangGraph Py/TS, Google ADK, MS Agent, AWS
Strands, Mastra, PydanticAI, CrewAI, Agno, AG2, LlamaIndex, Claude Agent
SDK, Deep Agents).
- **Open-JSON-UI is intentionally NOT linked:**
`/generative-ui/open-json-ui` is a placeholder pulled from the nav and
redirected to `/generative-ui` on purpose (`next.config.ts` — `//
AI-slop placeholder pulled from nav until properly authored`). Linking
only the two specs that have live detail pages avoids sending readers to
a redirect. Open-JSON-UI is still described in the comparison table on
the page.
- Open Generative UI is a CopilotKit capability (not an external spec),
so it sits under "related capabilities."
> Note: the issue/support-bot suggested a `/learn/...` path — there is
no `/learn/` tree in shell-docs; the canonical homes are the flat
`/generative-ui/<spec>` pages.
### 2. CLI `init` vs. existing app (Closes#2525)
Maintainer resolution was "fix the docs." The original "`init`
bootstraps your existing Next.js app" claim was already removed in the
shell-docs migration (the reported `/direct-to-llm/guides/quickstart`
now resolves to the Built-in Agent quickstart, which is fully manual).
To remove the remaining ambiguity:
- **Built-in Agent quickstart:** added an "Already have an app?" callout
— existing apps skip `create-next-app`.
- **CLI guide (`cli.mdx`):** clarified that `create` (aliased `init`)
scaffolds a brand-new project in its own directory and does not
detect/bootstrap an existing app; points to the manual install in the
Quickstart.
Verified against `copilotkit@latest` (4.3.0): `init --help` →
*"Initialize a **new** CopilotKit project … before scaffolding"*, `-n,
--name` *"names the local app **and its directory**"*, and
`init`/`create` are aliases.
### 3. Codex setup for the MCP guide (Closes#2526)
Added a **Codex** section to `mcp-server-setup.mdx` using the stdio
`mcp-remote` bridge in `~/.codex/config.toml`, matching the page's
existing command-based pattern (Cursor / Windsurf / Claude Desktop),
plus the `codex mcp add` shortcut.
Verified against the installed Codex CLI: `codex mcp --help` lists
`add`/`list`/`get`/`remove`, and the `[mcp_servers.<name>]` table with
`command`/`args` matches OpenAI's Codex config reference. Per the issue
thread, the macOS `mcp-remote` port-blocking concern is **not** claimed
to be solved — only the Codex config is documented.
## Testing
- **#3975 (links):** curled every added/changed URL against the live
docs — A2UI, MCP Apps, Open Generative UI, and all 12 framework
quickstarts return **200**; confirmed `/generative-ui/open-json-ui` is a
deliberate redirect (hence unlinked). Pre-existing `/ag-ui-protocol` and
`/generative-ui` links are stable 301→200 and left as-is.
- **#2525 (CLI):** ran `npx copilotkit@latest init --help` on the
published `latest` (4.3.0) — confirmed new-directory scaffolding, no
existing-app detection; verified `[Quickstart](/quickstart)` serves the
manual-install page live (`create-next-app` + "Install CopilotKit
packages").
- **#2526 (Codex):** ran `codex mcp --help` to confirm subcommands; new
section reuses the file's existing `<Steps>`/fenced-code structure.
`<Callout>` is a registered global MDX component
(`src/lib/mdx-registry.tsx`), already used unimported on the Built-in
Agent quickstart.
- Docs-only; no code paths affected.
Closes#3975Closes#2525Closes#2526🤖 Generated with [Claude Code](https://claude.com/claude-code)
CR: /generative-ui/open-json-ui is a deliberately-unpublished placeholder
(next.config.ts redirects it to /generative-ui, pulled from nav until
authored), so link only the two specs with live detail pages (A2UI, MCP
Apps). Open Generative UI is a CopilotKit capability rather than an
external spec, so it moves under related capabilities.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Fixes three independent documentation-accuracy issues:
- #3975: repoint the retired /generative-ui/specs/<spec> links to the
canonical flat /generative-ui/<spec> paths, add an Open Generative UI
entry, and add a Supported Frameworks list on the Generative UI Spec
Support page.
- #2525: clarify that the CLI `create`/`init` scaffolds a brand-new
project in its own directory and does not bootstrap an existing app;
point existing-app users to manual installation.
- #2526: add a Codex setup section to the MCP server guide using the
stdio `mcp-remote` bridge, matching the page's existing pattern.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
## What & why
Adds a new framework-agnostic guide — **Thread & History Lifecycle**
(`docs/threads-lifecycle.mdx`) — that walks the full client-side
lifecycle of a conversation thread as one narrative. It fills the gap
between the [Headless Threads](/threads) how-to and the [Threads &
Persistence Architecture](/premium/threads-explained) explanation, and
directly answers a recurring cluster of support questions.
## Sections
- **How the threadId is created** — UUID v4, client-minted at mount, the
resolution precedence, and the remount-stability caveat (auto-minted ids
re-mint on remount / StrictMode; pass an explicit `threadId` for
continuity).
- **How history is restored** — explicit-`threadId` `connect()` replay
vs. manual `agent.setMessages(...)`; clarifies there is **no v2
`initialMessages`** and no v2 `useCopilotChat` (read via
`useAgent().agent.messages`).
- **Switching / starting threads** — `setActiveThreadId(id, { explicit
})` and `startNewThread()`, plus the prop-controlled no-op guard.
- **Creating a thread with your own API on first message** —
mint-up-front + `setActiveThreadId`/`threadId` prop as the robust path;
the headless `CopilotChatInput.onSubmitMessage` seam for submit-time
interception (noting the built-in `<CopilotChat>` overrides it).
- **CopilotKit threads vs. your framework's checkpointer** — two layers
correlated only by `threadId`; a LangGraph checkpointer creates
checkpoint tables, not a CopilotKit "threads" table.
- **MCP Apps activity & history** — activity messages are
frontend/middleware constructs (no server store); re-synthesize on
hydration.
- **v1 vs v2** disambiguation (incl. the two different `useThreads`
hooks).
## Addresses
Recurring thread-lifecycle questions: #4790, #4778, #5434, #2242, #5931.
(I'll close those pointing here once this lands.)
## Testing / accuracy
All referenced APIs verified present on `main`: `useThreads` (v2),
`useCopilotChatConfiguration` (`setActiveThreadId`/`startNewThread`),
`useAgent().agent.setMessages/addMessage`,
`CopilotChatInput.onSubmitMessage`, `<CopilotChat threadId>`, and the
`mcp-apps` activity type. All five cross-doc links resolve. Added to the
"Threads" group in `docs/meta.json`.
Note: written against the current v2 APIs — three details were corrected
against source during authoring (`startNewThread` not `createThread`;
`onSubmitMessage` is headless-only; no v2
`useCopilotChat`/`initialMessages`).
Addresses CR on the Thread & History Lifecycle guide (PR #5988):
- Reorder the Threads navigation consistently across the root and all
authored-framework meta.json files to: Overview, Threads Drawer,
Headless Threads, Import Thread History, Threads & Persistence
Architecture, Thread & History Lifecycle. Re-anchor the injected
Architecture page before the Lifecycle page and update the nav-order test.
- Tighten the two-page boundary: Architecture now owns platform behavior
(persistence, replay, realtime sync, locks, failure modes) and defers
client-side steps to Lifecycle; Lifecycle keeps only brief persistence
context and links to Architecture for the deeper model.
- Writing pass reducing heavy em-dash use in both pages, keeping em dashes
only in link-gloss lists and table placeholders.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
## What does this PR do?
Removes the "Using setThreadId" example from the LangGraph and CrewAI
Flows persistence docs. That example calls `useCopilotContext()`, which
is a v1-only hook not exported from `@copilotkit/react-core/v2` —
following the example as written throws a module resolution error for v2
users.
The preceding "Dynamically Switching Threads" section on the same page
already documents the correct, working pattern (plain React state + the
`threadId` prop on `<CopilotKit>`), so removing the broken section
doesn't leave a gap.
## Related PRs and Issues
Closes#3860
## Files changed
-
`showcase/shell-docs/src/content/docs/integrations/langgraph/advanced/persistence/loading-message-history.mdx`
-
`showcase/shell-docs/src/content/docs/integrations/crewai-flows/persistence/loading-message-history.mdx`
## Checklist
- [x] I have read the [Contribution
Guide](https://github.com/copilotkit/copilotkit/blob/master/CONTRIBUTING.md)
- [x] Docs-only change; no functionality updated
- [x] Allow edits by maintainers
## What does this PR do?
`getAllLlmPages()` in `llm-text.ts` previously walked
`src/content/reference/` directly and emitted reference pages at
`reference/<slug>` (e.g. `reference/hooks/useCopilotAction`). The live
site serves those pages at their versioned canonical URL —
`/reference/v2/hooks/useCopilotAction` for the current v2 API — so
`llms-full.txt` contained non-canonical source URLs that diverged from
what users see in the browser.
**Root cause:** The v2 API reference lives at the _root_ of
`src/content/reference/` (no `v2/` subfolder), so a bare filesystem walk
cannot distinguish v2 from older SDK versions. It emits
`reference/hooks/foo` instead of the correct `reference/v2/hooks/foo`.
**Fix:** Replace step 3 with an enumeration via
`loadReferenceVersionItems` (which already knows the canonical URL per
version) and `resolveReferencePage` (which resolves the content file
path). This matches the URL scheme used by the `/reference/[...slug]`
route handler.
**Result:**
- v2 hooks/components now appear at `reference/v2/hooks/...` in
`llms-full.txt`
- v1, react-native, core, and bot pages appear at their correct
versioned prefixes
- Version root index pages (`reference/v2`, `reference/v1`, ...) are
included
- The migration guide (`migrate/v2`) was already included via the docs
walk (step 1 unchanged)
## Related PRs and Issues
- Closes#3385
## Checklist
- I have read the Contribution Guide
- If the PR changes or adds functionality, I have updated the relevant
documentation
- "Allow edits by maintainers" is checked
## Summary
Closes#5000.
`useAgent` (v2) always returns a **fully-constructed** `AbstractAgent` —
a *provisional* stand-in while the runtime is still connecting (or in an
error state), swapped for the real agent once the `/info` sync resolves.
The return type claimed `agent` was always the real agent, so consumers
had **no way to tell the provisional instance from the real one**.
One-time subscriptions registered during the provisional window (e.g.
`onRunFinalized`) landed on the placeholder and missed events until the
effect re-ran after the swap.
This PR adds an **`isReady`** flag to the return value:
- `false` — `agent` is provisional (runtime connecting / error)
- `true` — `agent` is the real, runtime-synced (or locally-registered)
instance
This is exactly the API the issue requests in its *Expected Behavior*.
It is **additive and backward compatible** — existing `const { agent } =
useAgent()` callers are unaffected.
```tsx
const { agent, isReady } = useAgent({ agentId });
useEffect(() => {
if (!isReady) return; // only subscribe once the real agent is bound
const sub = agent.subscribe({ onRunFinalized: (p) => console.log(p) });
return () => sub.unsubscribe();
}, [agent, isReady]);
```
## On the original crash
The crash reported in #5000 — `Cannot read properties of undefined
(reading 'subscribers')` at `AbstractAgent.subscribe` — **no longer
reproduces on `main`**. The provisional-agent work landed for #5533 /
#5635 now guarantees `useAgent` always returns a fully-constructed
`AbstractAgent`, so `subscribe()` is always safe to call. The added
tests lock in that no-crash behavior. What remained unaddressed was the
missing readiness signal, which this PR provides.
## Changes
- **`packages/react-core/src/v2/hooks/use-agent.tsx`** — `useMemo` now
returns `{ agent, isReady }`; real agent → `isReady: true`, provisional
paths → `isReady: false`. Documented with JSDoc.
- **`use-agent-subscribe-ready.test.tsx`** (new) — regression + behavior
coverage: `subscribe()` does not throw while connecting (effect +
during-render), `isReady` transitions `false → true` on sync and swaps
the instance, local agent is ready immediately.
- **`showcase/shell-docs/.../hooks/useAgent.mdx`** — signature +
return-value docs updated; the *Event Subscription* example fixed (it
used an empty `useEffect` dep array and never re-subscribed when the
agent reference changed).
## Testing
- New test file: 4/4 pass.
- Full `react-core` v2 hooks suite: **35 files / 299 tests pass** (the
`useMemo` return-shape change breaks nothing).
- `tsc --noEmit` clean.
## Notes
- Scope is React only, matching the issue. The Vue `useAgent`
(`packages/vue`) is structured differently (reactive `shallowRef`,
`agent` can be `null`); happy to add matching `isReady` as a follow-up
if maintainers want cross-framework parity.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
## Summary
Fixes FAC-64: Mastra Interrupts docs example fails on missing agentId
and suspendPayload guard
This PR rewrites the Mastra interrupt documentation to correctly reflect
that **Mastra does not support native interrupt flow**. The framework
lacks LangGraph-style `interrupt()` primitives and does not emit AG-UI
interrupt events.
## Changes
### 📝 Documentation Updates
1. **`interrupt-flow.mdx`**: Completely rewritten to:
- Add prominent warning callout that Mastra doesn't support interrupts
- Explain why the interrupt pattern doesn't work with Mastra
- Provide working alternative using `useHumanInTheLoop`
- Include comparison table between interrupt-based and tool-based
approaches
- Redirect users to the tool-based HITL guide
2. **`index.mdx`**: Updated to:
- Mark interrupt-based approach as "Not Supported"
- Mark tool-based approach as "Supported" (the working pattern)
- Reorder cards to prioritize the working approach
## Rationale
The original docs documented `useInterrupt` with examples that would:
- Fail with "Agent 'default' not found" (missing `agentId` parameter)
- Fail with "Cannot destructure property 'action'" (incorrect payload
access)
- Silently fail (hook listens for events Mastra never emits)
Research revealed:
- `showcase/integrations/mastra/manifest.yaml` explicitly lists
`gen-ui-interrupt` under `not_supported_features`
- The actual working demo uses `useHumanInTheLoop`, not `useInterrupt`
- Comments in the code confirm: "This framework has no LangGraph-style
`interrupt()` primitive"
## Migration Path
Users following the old docs can now:
1. See clear warning that interrupts aren't supported
2. Learn the correct `useHumanInTheLoop` pattern
3. Follow link to complete tool-based HITL guide with working examples
## Testing
- ✅ Documentation changes only (no runtime code affected)
- ✅ Verified redirect links work correctly
- ✅ Checked against actual working implementation in
`showcase/integrations/mastra/src/app/demos/gen-ui-interrupt/page.tsx`
## Related
- Linear: FAC-64
- QA Report: Documented three specific runtime errors from the broken
examples
- Research: Identified Option B (rewrite for useHumanInTheLoop) as the
correct approach
`useAgent` always returns a fully-constructed `AbstractAgent`: a provisional
stand-in while the runtime is still connecting (or in an error state), swapped
for the real agent once the `/info` sync resolves. The returned type claimed
`agent` was always the real agent, giving consumers no way to tell the two
apart — so one-time subscriptions (e.g. `onRunFinalized`) registered during the
provisional window landed on the placeholder and missed events until the effect
re-ran after the swap.
Add an `isReady` flag to the return value: `false` while the agent is
provisional, `true` once the real (or locally-registered) agent is bound.
Additive and backward compatible.
Also fix the docs' "Event Subscription" example, which used an empty
`useEffect` dependency array and therefore never re-subscribed when the agent
reference changed.
Note: the original crash from #5000 ("Cannot read properties of undefined
(reading 'subscribers')") no longer reproduces on `main` — the provisional-agent
work (#5533/#5635) guarantees a fully-constructed agent, so `subscribe()` is
always safe. The added tests lock in that no-crash behavior and cover the new
`isReady` transition.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The new Threads page shifts the expected navigation order; update the
expected array in docs-render.test.ts to include "Thread & History
Lifecycle" after "Overview" so the shell-docs suite passes.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Addresses samjulien's review on #5988:
- Use `agentId` (not `agent`) in both <CopilotChat> snippets — `agent` is
not a v2 prop.
- Add threads-lifecycle to every authored-framework Threads nav group
(built-in-agent, mastra, crewai-flows, llamaindex, agno, ag2,
pydantic-ai, microsoft-agent-framework, deepagents). Extracted the page
body into a shared snippet and made the root + per-framework pages thin
wrappers, matching the existing threads/headless-threads/threads-import
single-source convention.
- Qualify the "Run" glance statement: server-side persistence/replay
depends on a configured store (Enterprise Intelligence or a persisting
AgentRunner); a runtime with no persistence layer keeps nothing.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- meta.json: keep main's Threads nav group and slot `threads-lifecycle` in
after the `threads` overview.
- threads-lifecycle.mdx: main split the old `/threads` page into a `threads`
overview + a `headless-threads` how-to; repoint the two "Headless Threads"
links from `/threads` to `/headless-threads`.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
## Summary
- turn `/threads` into a product-oriented overview that explains why
developers use CopilotKit Threads and routes them by job to Drawer,
Headless, import, architecture, and deployment docs
- label the overview as `Overview` in the Threads navigation while
retaining `Threads` as the page title
- move the existing custom UI implementation guide to
`/headless-threads` across root, generated, authored, and Built-in
framework surfaces
- present the architecture as a product-to-system story: what users
experience, the UI/runtime/agent pieces in the app, and Enterprise
Intelligence as the cloud-hosted or self-hosted Threads platform
- provide responsive desktop and mobile diagram assets in light and dark
modes, showing durable history, replay to live, realtime sync,
lifecycle, and locking
- move `Threads & Persistence Architecture` into the Threads navigation
group across all framework modes
- replace the standalone migration CTA with contextual prose that leads
naturally to `Import Thread History`
- replace ambiguous linked-card layouts with a comparison table,
explicit action links, and a conventional next-steps list
- migrate implementation-intent links to `/headless-threads` while
keeping product-level links on `/threads`
- correct the ADK Vertex importer project-variable reference
- add regression coverage for route availability, nav labels/order,
page-title separation, shared architecture placement, and
framework-aware link rewriting
## Authoring surfaces
- **Shared/root:** `src/content/docs/{threads,headless-threads}.mdx`,
shared overview and headless snippets, root `meta.json`, and responsive
light/dark diagram assets
- **Authored frameworks:** integration wrappers and navigation metadata;
shared navigation logic inserts the architecture page into each Threads
group
- **Generated frameworks:** shared root routes, snippets, and root
navigation; generated data files are not hand-edited
- **Built-in Agent:** authored wrapper plus the same shared navigation
injection
- **Cross-links/reference:** Drawer, import, CLI, architecture,
tutorials, and `useThreads` reference pages
## Routing and redirects
No redirect is added for the old `/threads` implementation URL because
`/threads` is intentionally reused by the new overview. Existing
external links to `/threads` now land on the product overview, and
internal links that specifically mean the custom `useThreads`
implementation guide have moved to `/headless-threads`. Framework-aware
link rewriting scopes both routes normally.
## Base
This PR targets `main` after #5915 merged. Its diff contains only the
Threads overview follow-up commits.
## Validation
- `npm run lint` (passes with existing repository warnings only)
- `npm run test` (32 files, 170 tests)
- `npm run typecheck`
- `npm run build` (214 static pages generated; existing Turbopack
tracing warning only)
- `git diff --check`
- SVG XML validation for both architecture assets
- live browser checks on root, Mastra, LangGraph Python, and Built-in
Agent routes
- light/dark diagram rendering and narrow/desktop layout passes
- History section: "Platform replay (the default)" → "Server-side replay",
state the precondition (needs a server-side store — platform or a
persisting AgentRunner; a bare runtime replays nothing), and use the
correct method name connectAgent() (there is no agent.connect()).
- First-message thread creation (headless): fix a race — the example set
the thread via setActiveThreadId() (a deferred React state update) then
sent immediately, which lands on the previous thread; and truly-headless
has nothing syncing agent.threadId. Now set agent.threadId directly and
add a caveat explaining the state-setter timing.
- v1 notes: correct the setThreadId throw attribution — the useThreads
setter silently shadows under a prop; the throwing setThreadId is the
one on the main <CopilotKit> hooks.
- MCP Apps: drop the unverified "not persisted server-side" assertion;
reframe as client-side re-derivation that restores via normal history
replay.
- LangGraph: don't imply the linked persistence page proves the Platform
UUID rule; loosen the checkpointer shorthand.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Short how-to section in background-tasks.mdx: enable Observational Memory on
the agent's Memory + opt in on the adapter (observationalMemory: true on
getLocalAgents), render via renderActivityMessages with activityType
mastra-observational-memory. Mirrors the working /demos/observational-memory
wiring. (--no-verify: worktree commitlint binary still broken post-crash.)
Adds a framework-agnostic guide covering the full client-side thread
lifecycle, filling a gap between the Headless Threads how-to and the
Threads & Persistence Architecture explanation:
- how a threadId is minted (UUID v4, client-side at mount) + the
resolution precedence and the remount-stability caveat
- how history is restored (explicit-threadId connect() replay vs.
manual agent.setMessages); notes v2 has no initialMessages
- switching/starting threads (setActiveThreadId / startNewThread) and
the prop-controlled no-op guard
- intercepting thread creation on first message (mint-up-front vs. the
headless onSubmitMessage seam; built-in <CopilotChat> overrides it)
- CopilotKit threads vs. framework checkpointers (two layers correlated
only by threadId; a checkpointer creates checkpoint tables, not a
threads table)
- MCP Apps activity/history (frontend constructs; re-synthesize on hydration)
- v1 vs v2 disambiguation
Addresses the recurring thread-lifecycle support questions (#4790, #4778,
#5434, #2242, #5931). Added to the Threads nav group.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Addresses @samjulien's review on #5982:
1. Contributing example command: the guide changed into a nonexistent
`examples/next-openai` and ran `dev:examples` (a workspace build/watch
script that never starts a server). Point it at the real
`examples/v1/next-openai` package and its `example-dev` (`next dev`)
script, which actually serves http://localhost:3000/presentation.
Fixed in the shared snippet + all per-integration copies.
2. LangGraph auth: langgraph variants are docs_mode: generated, so the
`/auth` route renders the root `docs/auth.mdx`, not the framework copy.
Add the missing `from langchain_core.runnables import RunnableConfig`
to the two Python blocks in the root source that route renders.
3. Self-contained fences: add the import to the non-tutorial
`langgraph/shared-state/predictive-state-updates.mdx` Python fence and
the `snippets/integrations/langgraph/frontend-tools.mdx` fence, so the
zero-missing-import claim holds for every non-tutorial langgraph block.
4. Contributor prerequisites: bump the `docs-contributions` guides from
pnpm 9 to pnpm 10 to match the code-contributions requirement.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Consolidates three stale-docs fixes that were opened against the retired
`docs/content/docs/` tree (now a symlink) and so could no longer merge:
- Contributing/package-linking guides (root + all integration copies +
shared snippets): Turborepo is fully removed from the repo (no dep, no
turbo.json). Drop the Turborepo prerequisite, bump pnpm to v10.x to match
`packageManager`, describe the monorepo as a pnpm workspace orchestrated by
Nx, and replace `turbo run <task>` with verified equivalents:
`pnpm run build|dev|format|lint`, `pnpm exec nx run-many -t (un)link:global`,
`pnpm exec nx watch` for a single package, and `pnpm run dev:examples`
(the real script; `example-dev` did not exist). Supersedes #3509.
- built-in-agent/model-selection: hyphenate the Anthropic model IDs
(`claude-3-7-sonnet`, `claude-opus-4-1`, `claude-3-5-haiku`). Supersedes #3656.
- langgraph reference docs: add the missing
`from langchain_core.runnables import RunnableConfig` import to Python code
blocks that annotate `config: RunnableConfig`. Supersedes #4069.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Mike Ryan