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>
## Summary
This PR updates thread import documentation and threads navigation
across shell-docs, including a follow-up that makes the supported
CLI-only import journey explicit.
## What changed
- Adds thread import documentation:
- Root generic guide at `/threads-import` for frameworks without a
source-specific importer page.
- Google ADK-specific guide at `/google-adk/threads-import`.
- LangGraph-specific guide at `/langgraph-python/threads-import`, plus
generated LangGraph framework routes through the framework resolver.
- Authored framework wrappers so Mastra, AG2, Agno, Built-in Agent,
CrewAI Flows, DeepAgents, LlamaIndex, Microsoft Agent Framework, and
PydanticAI can surface the generic guide.
- Updates the CLI and import journey:
- Describes the CLI as supporting both cloud-hosted and self-hosted
Enterprise Intelligence.
- States up front that import runs from an app created with the
CopilotKit CLI and Enterprise Intelligence enabled.
- Clarifies that import uses the project already selected for the
current directory.
- Shows the source import commands before the optional `project select`
explanation, while still directing users to change targets before
running the dry run.
- Removes the suggestion that `skills onboard` plus `project select` can
add Enterprise Intelligence to an arbitrary existing app.
- Keeps the CLI import section concise and links to the complete generic
and source-specific guides.
- Clarifies future thread continuity:
- Threads Drawer uses the shared `CopilotChatConfigurationProvider`, so
selecting a thread updates the active `threadId` without separate state
wiring.
- Headless Threads uses `useThreads`; the app stores the selected
`thread.id` and passes it to the chat component as `threadId`.
- ADK and LangGraph guides retain source-specific stable ID mapping
guidance, including the LangGraph UUID caveat.
- Removes source-guide links that rewrote to the current framework page
and created circular navigation.
- Adds and organizes Threads Drawer docs:
- Extracts shared Threads Drawer content into a reusable snippet.
- Adds root and authored-framework wrapper pages.
- Moves Threads Drawer into a new expanded Threads nav grouping
alongside Headless Threads and Import Thread History.
- Renames and reorganizes threads docs:
- Relabels the existing `Threads` guide as `Headless Threads`.
- Removes the root prebuilt-components nav entry for Threads Drawer so
generated frameworks do not show it in two places.
- Updates root, authored, generated, and Built-in Agent nav metadata so
the Threads grouping is consistent.
- Updates nav tests to recognize pages nested inside authored-framework
groups.
## Validation
Run from `showcase/shell-docs`:
- `npm run lint` passes with the existing repository warning set.
- `npm run typecheck` passes.
- `npm run test` passes: 32 files and 167 tests.
- `npm run build` passes and generates 214 static pages; it reports the
existing Turbopack NFT tracing warning.
- Rendered and link-checked locally:
- `/cli`
- `/threads-import`
- `/mastra/threads-import`
- `/google-adk/threads-import`
- `/langgraph-python/threads-import`
- Root and framework-specific Threads Drawer and Headless Threads links
## Redirects
No redirect URLs were added or required:
- `Threads` was relabeled to `Headless Threads`, but the slug remains
`/threads`.
- `CopilotThreadsDrawer` was relabeled to `Threads Drawer`, but the URL
remains `/prebuilt-components/copilot-threads-drawer` and framework
equivalents.
- Threads Drawer moved in navigation, but the route did not move.
- `Import Thread History` is new at `/threads-import` and framework
routes such as `/mastra/threads-import`, `/google-adk/threads-import`,
and `/langgraph-python/threads-import`, so there is no prior URL to
redirect.
- The generated-framework routing change only selects framework-specific
content for the new `threads-import` slug.
Benjamin Taylor