Commit Graph

849 Commits

Author SHA1 Message Date
Mike Ryan dacc667355 fix(docs): resolve Angular overview guide links 2026-07-27 09:38:01 -07:00
Mike Ryan 852990ccd1 fix(docs): select Angular quickstart branch before MDX 2026-07-27 09:38:01 -07:00
Mike Ryan b7e83d7c1f docs: make Angular journeys capability-aware 2026-07-27 09:38:01 -07:00
Mike Ryan 8a2844b571 docs: enforce angular-only documentation routes 2026-07-27 09:38:01 -07:00
Mike Ryan 9988c23890 docs: render shared concepts for Angular 2026-07-27 09:38:00 -07:00
Mike Ryan cc8689e21f fix(showcase): bundle Angular docs source in image 2026-07-27 09:38:00 -07:00
Mike Ryan a87f1c9a30 docs: close Angular information architecture gaps 2026-07-27 09:38:00 -07:00
Mike Ryan db732d3966 docs: complete Angular threads API journey 2026-07-27 09:38:00 -07:00
Mike Ryan 38333d3625 docs: enforce Angular parity across backend guides 2026-07-27 09:38:00 -07:00
Mike Ryan 92e5c31332 docs: align Angular metadata with rendered variants 2026-07-27 09:37:59 -07:00
Mike Ryan fcf2357c25 docs: add Angular-native content and source-backed snippets 2026-07-27 09:37:59 -07:00
Mike Ryan c569aa595d docs: make Angular share the full information architecture 2026-07-27 09:37:59 -07:00
Varun Nuthalapati 9f7fef178b docs(langgraph): fix emit-api-hook-mapping links and placeholder model
Point "See also" links at the /integrations/langgraph/ prefixed routes
(the bare /langgraph/... links 404), drop the dead Python SDK reference
link (no target page), and swap the placeholder "gpt-5.4" model string
for a real one (gpt-4o) in both code samples.

Addresses review feedback on #5483. The unrelated use-agent.tsx isReady
change was dropped by rebasing this branch onto upstream/main and
carrying forward only the docs commit — isReady already ships on main
via #6041.
2026-07-24 21:45:31 -07:00
Varun Nuthalapati dda8754f4a docs(langgraph): document emit API to v2 hook mapping end-to-end
Adds a new page under integrations/langgraph/advanced/ explaining how
LangGraph SDK backend emit functions (copilotkit_emit_tool_call,
copilotkit_customize_config) connect to React v2 frontend hooks
(useFrontendTool, useComponent). Includes a mapping table, two
concrete end-to-end examples, and a decision guide.

Closes #3301
2026-07-24 21:44:42 -07:00
Ben Taylor a00592f115 docs(channels): add Channels SDK documentation (#6031)
## What does this PR do?

Adds documentation for the **`@copilotkit/channels` SDK** — running a
CopilotKit agent as a bot inside Slack, Teams, WhatsApp, Telegram, and
Discord. New `---Channels---` nav group under `showcase/shell-docs`.

**Guides**
- Overview (agent + JSX + channel, end to end), Quickstart (TanStack
factory agent on the Intelligence adapter)
- UI Library (JSX component rendering, callbacks, component
registration, `{ raw }` escape hatch)
- Interactive flows: Human-in-the-loop (+ agent-initiated
`onInterrupt`), Reactions (+ emoji helpers), Modals
- Commands & global reactions, Files & multimodality, MCP (agent-side),
Channel configuration, Tools & context
- Platforms: overview of what Intelligence handles for you, plus
per-adapter pages (Teams / WhatsApp / Slack / Telegram / Discord) with
built-in tools/context

**API reference** (signatures pulled from the installed `0.2.1` type
definitions): Channel, Thread, JSX callbacks.

All examples use the Intelligence adapter except the platform-specific
pages, which use each platform's own adapter. Every internal link
resolves; MDX validated.

## Related PRs and Issues

- N/A

## Checklist

- [x] I have read the Contribution Guide
- [x] If the PR changes or adds functionality, I have updated the
relevant documentation
- [x] "Allow edits by maintainers" is checked

🤖 Generated with [Claude Code](https://claude.com/claude-code)
2026-07-24 11:42:08 -05:00
Benjamin Taylor 4f3c820908 docs(channels): add required agents:{} to runtime snippets + keep-alive note (adversarial review)
Adversarial pass caught that every new CopilotRuntime({...}) snippet omitted the
required non-optional `agents` field (TS2741 on copy-paste) — added `agents: {}`
matching examples/slack/app/managed.ts. Also noted that the managed index/mcp
snippets end at ready() with no server, so a reader's process would exit — added a
keep-alive pointer to the Quickstart's full listener mount.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-24 10:59:04 -05:00
Benjamin Taylor 6d1205d0f5 docs(channels): reconcile with Plan C — runtime-driven lifecycle, Intelligence key required
Channels run only through the Intelligence runtime now (PR #6145): public
channel.start()/stop()/addAdapter() are removed. Updated the run path to
new CopilotRuntime({ intelligence, channels }) + handler/listener.channels.ready()/stop()
across quickstart, index, mcp, configuration, the 5 platform pages, and the
channel reference; reframed the managed-vs-direct table (both require an
Intelligence key — the difference is who holds the platform credentials);
name is now required (the runtime keys lifecycle by it); surfaced the
Intelligence-key (free tier) prerequisite. Standardized the managed pattern on
zero-adapter createChannel({ name }) (runtime attaches the managed transport),
matching examples/slack/app/managed.ts.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-24 10:44:21 -05:00
Mike Ryan 1c0c769562 docs(angular): add task guides 2026-07-23 08:10:21 -07:00
Mike Ryan 06df1ea155 docs(angular): improve standalone documentation 2026-07-23 07:51:53 -07:00
Mike Ryan 7ccd34a05d feat(showcase): checkpoint 5 - hardening and final exposure 2026-07-23 07:14:55 -07:00
Mike Ryan 4d32d941eb feat(showcase): checkpoint 4 - all supported features and docs 2026-07-23 07:14:55 -07:00
Mike Ryan fec70d086f feat(angular): checkpoint 2 - core and package 2026-07-23 07:14:55 -07:00
Mike Ryan 873cbb8b6c feat(showcase): checkpoint 1 - baseline and registry 2026-07-23 07:12:53 -07:00
Sam Julien cd349a8940 fix: avoid the PostHog import lint warning 2026-07-22 15:47:08 -07:00
Sam Julien d72c03e7b9 docs: track Rich Threads conversion actions 2026-07-22 15:46:32 -07:00
Sam Julien 21eede7d12 docs: finalize the Rich Threads journey 2026-07-22 15:46:19 -07:00
Sam Julien e00435a7da docs: apply Rich Threads review feedback 2026-07-22 11:56:04 -07:00
Sam Julien 827003e7c8 test: verify Rich Threads navigation contracts 2026-07-22 11:20:47 -07:00
Sam Julien 2b72479da2 docs: fix Rich Threads onboarding guidance 2026-07-22 11:03:01 -07:00
Sam Julien a715e1f70b docs: align Rich Threads support boundaries 2026-07-22 10:57:07 -07:00
Sam Julien 45ce56b729 docs: clarify thread history synchronization 2026-07-22 10:45:51 -07:00
Sam Julien 540a980abb docs: fix Rich Threads review findings 2026-07-22 10:36:08 -07:00
Sam Julien 68ab0740c6 docs: introduce Rich Threads overview journey 2026-07-22 10:30:43 -07:00
Mark 64daf49638 feat(showcase/mastra): v1 bridge alpha + reasoning/streaming out of not_supported (OSS-381) (#5798)
## 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.
2026-07-21 16:44:25 -07:00
Mark f986cff0cb Merge branch 'main' into claude/brave-kirch-8dbf00 2026-07-21 10:10:45 -07:00
Jordan Ritter d1b07d4513 fix(showcase): stage catalog-flatten in generator envs
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.
2026-07-20 22:36:14 -07:00
Tyler Slaton 50805ab47d docs: fix stale quickstart/link references and add MCP Codex setup (#6079)
## 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 #3975
Closes #2525
Closes #2526

🤖 Generated with [Claude Code](https://claude.com/claude-code)
2026-07-20 15:10:16 -07:00
Benjamin Taylor 7869d31e64 docs: drop unpublished Open-JSON-UI link, move Open Generative UI to related
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>
2026-07-20 16:16:15 -05:00
Benjamin Taylor c9511cf4f9 docs: fix stale quickstart/link references and add MCP Codex setup
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>
2026-07-20 16:03:16 -05:00
Sam Julien 5a35379906 docs: add Thread & History Lifecycle guide (#5988)
## 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`).
2026-07-20 11:45:43 -07:00
Benjamin Taylor 6fba48faa9 docs(threads): reorder Threads nav and tighten lifecycle/architecture boundary
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>
2026-07-20 12:31:27 -05:00
Ran Shemtov bdd3a8232d Merge branch 'main' into claude/brave-kirch-8dbf00 2026-07-20 18:27:41 +02:00
Ben Taylor 30cc551a9b docs(langgraph,crewai-flows): remove broken useCopilotContext example (#5821)
## 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
2026-07-20 10:58:16 -05:00
Ben Taylor e91ae56372 docs(shell-docs): emit canonical versioned URLs for reference pages in llms-full.txt (#5486)
## 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
2026-07-20 10:45:17 -05:00
Ran Shem Tov 93c7369e85 Merge remote-tracking branch 'origin/main' into claude/brave-kirch-8dbf00
# Conflicts:
#	showcase/scripts/__tests__/aimock-fixtures.test.ts
2026-07-20 11:14:15 +02:00
Ben Taylor 5595cf76c6 fix(react-core): expose isReady from useAgent to guard agent subscriptions (#5000) (#6041)
## 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)
2026-07-19 22:44:41 -05:00
Ben Taylor 0035a7e387 docs(mastra): clarify that interrupts are not supported, redirect to tool-based HITL (#5895)
## 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
2026-07-19 22:14:20 -05:00
Aria Zhao e5c1af418a fix(react-core): expose isReady from useAgent so subscriptions can target the real agent (#5000)
`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>
2026-07-18 04:39:46 +00:00
Benjamin Taylor a6768cf1e6 docs: add Thread & History Lifecycle to docs-render expected nav order
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>
2026-07-17 12:25:30 -05:00
Benjamin Taylor fa319dffe5 docs: address CR on threads-lifecycle guide (agentId prop, per-framework nav, persistence caveat)
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>
2026-07-17 12:02:30 -05:00