copilotkit 4.8.2 → 4.8.4

package/onboarding/index.json

@@ -0,0 +1,179 @@
+{
+  "root": "authenticate/start",
+  "prompts": [
+    {
+      "edges": [
+        "credentials/plan",
+        "unsupported/no-validated-path"
+      ],
+      "milestone": "authenticate",
+      "name": "authenticate/start"
+    },
+    {
+      "edges": [
+        "implementation/build-and-validate",
+        "unsupported/no-validated-path"
+      ],
+      "milestone": "credentials",
+      "name": "credentials/finalize-plan"
+    },
+    {
+      "edges": [
+        "framework/langgraph-python",
+        "framework/langgraph-typescript",
+        "framework/google-adk",
+        "framework/ms-agent-python",
+        "framework/ms-agent-dotnet",
+        "framework/mastra",
+        "unsupported/no-validated-path"
+      ],
+      "milestone": "credentials",
+      "name": "credentials/plan"
+    },
+    {
+      "edges": [
+        "frontend/plan",
+        "unsupported/no-validated-path"
+      ],
+      "milestone": "framework",
+      "name": "framework/google-adk"
+    },
+    {
+      "edges": [
+        "frontend/plan",
+        "unsupported/no-validated-path"
+      ],
+      "milestone": "framework",
+      "name": "framework/langgraph-python"
+    },
+    {
+      "edges": [
+        "frontend/plan",
+        "unsupported/no-validated-path"
+      ],
+      "milestone": "framework",
+      "name": "framework/langgraph-typescript"
+    },
+    {
+      "edges": [
+        "frontend/plan",
+        "unsupported/no-validated-path"
+      ],
+      "milestone": "framework",
+      "name": "framework/mastra"
+    },
+    {
+      "edges": [
+        "frontend/plan",
+        "unsupported/no-validated-path"
+      ],
+      "milestone": "framework",
+      "name": "framework/ms-agent-dotnet"
+    },
+    {
+      "edges": [
+        "frontend/plan",
+        "unsupported/no-validated-path"
+      ],
+      "milestone": "framework",
+      "name": "framework/ms-agent-python"
+    },
+    {
+      "edges": [
+        "credentials/finalize-plan",
+        "unsupported/no-validated-path"
+      ],
+      "milestone": "frontend",
+      "name": "frontend/angular"
+    },
+    {
+      "edges": [
+        "credentials/finalize-plan",
+        "unsupported/no-validated-path"
+      ],
+      "milestone": "frontend",
+      "name": "frontend/nextjs"
+    },
+    {
+      "edges": [
+        "frontend/react-spa",
+        "frontend/nextjs",
+        "frontend/angular",
+        "frontend/vue",
+        "frontend/react-native",
+        "unsupported/no-validated-path"
+      ],
+      "milestone": "frontend",
+      "name": "frontend/plan"
+    },
+    {
+      "edges": [
+        "credentials/finalize-plan",
+        "unsupported/no-validated-path"
+      ],
+      "milestone": "frontend",
+      "name": "frontend/react-native"
+    },
+    {
+      "edges": [
+        "unsupported/no-validated-path"
+      ],
+      "milestone": "frontend",
+      "name": "frontend/react-spa"
+    },
+    {
+      "edges": [
+        "credentials/finalize-plan",
+        "unsupported/no-validated-path"
+      ],
+      "milestone": "frontend",
+      "name": "frontend/vue"
+    },
+    {
+      "edges": [
+        "proof/round-trip",
+        "unsupported/no-validated-path"
+      ],
+      "milestone": "implementation",
+      "name": "implementation/build-and-validate"
+    },
+    {
+      "edges": [],
+      "milestone": "proof",
+      "name": "proof/complete"
+    },
+    {
+      "edges": [
+        "proof/complete",
+        "unsupported/no-validated-path"
+      ],
+      "milestone": "proof",
+      "name": "proof/round-trip"
+    },
+    {
+      "edges": [],
+      "milestone": "subagent",
+      "name": "subagent/create-plan"
+    },
+    {
+      "edges": [],
+      "milestone": "subagent",
+      "name": "subagent/implement-and-validate"
+    },
+    {
+      "edges": [],
+      "milestone": "subagent",
+      "name": "subagent/inspect-repository"
+    },
+    {
+      "edges": [],
+      "milestone": "subagent",
+      "name": "subagent/prove-round-trip"
+    },
+    {
+      "edges": [],
+      "milestone": "unsupported",
+      "name": "unsupported/no-validated-path"
+    }
+  ]
+}

package/onboarding/prompts/authenticate/start.md

@@ -0,0 +1,83 @@
+# Start CopilotKit onboarding
+
+Act only as the orchestrator. Rely on subagents for all project work.
+Give every project task to a subagent.
+Do not inspect, change, implement, or validate the project yourself.
+Do not show prompt names, internal route IDs, subagent names, or storage field names to the developer.
+
+Work from the target project directory. For an existing project, start at its inspection
+root.
+
+Read only inside the target project directory. Every subagent you spawn inherits that
+limit, including one this graph does not name. Answer a CopilotKit API or configuration
+question from the documentation this graph gives you. Another checkout on this machine is
+not a source. The developer running this has none, so an answer taken from one is an
+answer they cannot get, and it hides the documentation gap that blocks them.
+
+Run `npx copilotkit@4.8.4 login --json` before any project work. This command checks the
+current session. It starts sign-in only as needed.
+
+Read its JSON Lines output in order:
+
+1. If it emits `authentication_url`, show only that URL to the developer.
+2. Tell the developer to open the URL and finish sign-in.
+3. Wait for the command to emit `type: completed`.
+4. If it emits `type: failed`, report the error and stop onboarding.
+
+Do not use `whoami` for this check. It has no JSON output and some failures exit with code
+zero. Do not put account tokens or credentials in the conversation.
+
+Spawn one research subagent. Give it the full text of the research brief at the end of this
+prompt and tell it to follow that brief and return only its findings. Add these tasks:
+
+- Find the target app or runtime directory that owns `.env` and CopilotKit setup.
+- Check whether `.copilotkit/project.json` has `projectId`, `projectSlug`, and `clerkOrgId`.
+- Check whether `.env` has a non-empty `INTELLIGENCE_API_KEY` entry.
+- Record the `.env` file modification time without returning it.
+
+Do not print either file or any secret value. Return only paths, presence checks, and missing
+field names. Wait for the subagent to finish.
+
+If a repository file exists, each finding must cite it. For an empty project, the subagent
+must cite its directory check and report absent parts.
+
+The findings must cover what the project is for, the agent, frontend, CopilotKit setup,
+authentication, credential names, and validation path. Do not ask the developer for facts
+that the repository answers.
+
+When the evidence is complete, run
+`npx copilotkit@4.8.4 onboard read credentials/plan`.
+
+If authentication or inspection stops onboarding, run
+`npx copilotkit@4.8.4 onboard read unsupported/no-validated-path`.
+
+## Research subagent brief
+
+Everything below the rule is the subagent's prompt. Give it verbatim.
+
+---
+
+# Inspect the repository
+
+Inspect the repository without changing it. Find evidence for:
+
+- what the project is for, in the project's own words
+- any existing agent framework
+- any existing frontend
+- current CopilotKit packages and configuration
+- authentication boundaries
+- names of required credential variables, without reading their values
+
+A project states what it is for in its `README.md`, in its package description, or in
+the prompt of an agent it already has. Quote that statement rather than rewriting it. An
+empty project carries it in the README alone, and that makes the README the whole of the
+evidence. State the purpose as unproved when the project never says.
+
+Gather what you need in as few commands as possible. Combine independent reads into one
+command rather than running them one at a time. Split a command only when its result decides
+what you run next.
+
+Return the file paths and a short finding for each item. State each absent or unproved item.
+Do not read, print, or return secret values. Do not read a file outside the project
+directory. Do not run or return another onboarding command. Stop after returning the
+findings to the main coding agent.

package/onboarding/prompts/credentials/finalize-plan.md

@@ -0,0 +1,185 @@
+# Select the Intelligence project and create the plan
+
+Use the selected framework, frontend, model vendor, model, documentation URLs, and
+repository findings. Ask the developer only for choices that the repository does not
+show. Do not change application code in this phase. Do not read, show, store, or request
+a secret value.
+
+## Select the Intelligence project
+
+Use the target app or runtime directory from the repository findings. If a nested app owns
+the runtime `.env` file, do not default to the repository root.
+
+If valid project fields and a non-empty `INTELLIGENCE_API_KEY` already exist, ask whether to
+keep that selection. Recommend keeping it to avoid minting another key. Ask the developer to
+confirm that the prior project selection had no key-provision warning.
+
+Reused project credentials remain unverified until an authenticated Intelligence call
+succeeds. Record that state in the plan.
+
+If the developer needs a project or another project, do the selection yourself from the
+target directory. Do not send the developer to another terminal.
+
+List the choices first:
+
+```text
+npx copilotkit@4.8.4 project list --json
+```
+
+With `--json` the payload is the only thing on standard output, so it is safe to parse.
+Show the developer the project names and ask which one to use, or ask for a name for a new
+project. This is the same kind of question as the frontend choice, so ask it here rather
+than ending the turn.
+
+Then record their answer, from the target directory:
+
+```text
+npx copilotkit@4.8.4 project select --project <slug-or-id> --json
+```
+
+Use `--create <name> --json` instead when they want a new project. The two flags cannot be
+combined. A slug that does not exist fails and lists the real ones, so a typo cannot record
+a selection that points at nothing.
+
+Read the JSON result. It reports `api_key_provisioned`. Key provisioning is deliberately
+non-fatal, so this command can persist the selection, warn on standard error, and still
+exit zero with no key written. Treat `api_key_provisioned` as false the same way as an
+error and stop onboarding: a scaffold with no key looks finished and is not.
+
+Never print the payload or any secret value.
+
+After a warning-free result, send the research subagent a follow-up check. Require it to
+confirm these facts without showing values:
+
+- `.copilotkit/project.json` has non-empty `projectId`, `projectSlug`, and `clerkOrgId` fields.
+- `.env` has a non-empty `INTELLIGENCE_API_KEY` entry.
+- If project selection ran, its selected slug matches `projectSlug`.
+- If project selection ran, the `.env` file was created or its modification time advanced.
+
+Do not print either file or any secret value. If a check fails, stop onboarding. A project
+selection success message alone does not prove key readiness. The CLI cannot prove key scope
+before an authenticated Intelligence call succeeds.
+
+## Where a model credential comes from
+
+The plan names the model credential variables. Finding their values is not its job.
+
+If the project has no value for one, ask the developer where it lives. Never read a file
+outside the project directory to find one. A key found that way belongs to another
+project: it bills that project for these model calls, points attribution at a project
+nobody chose, and leaves no trace, because the scaffold works.
+
+Asking where a credential lives is not requesting a secret value. Ask for a path, or ask
+the developer to write the value into the project's env file themselves. A path the
+developer names is theirs to give, including one outside the project. A path this run
+finds is not.
+
+If no answer comes, stop. Do not write a placeholder or an empty value. A scaffold
+carrying a dummy key looks finished and fails at the first model call, which is worse
+than stopping here.
+
+## Wire the runtime to Intelligence
+
+The key in `.env` does nothing on its own. The runtime reads no environment variable for
+it. The credential reaches the platform only when the runtime is constructed with an
+Intelligence client, and a runtime built without one compiles, serves, answers in a
+browser, and never touches the platform.
+
+Add this page to the selected documentation URLs for both subagents:
+
+- https://docs.copilotkit.ai/premium/connect-your-runtime.md
+
+Fetch it together with the pages already selected rather than on its own.
+
+Spawn one planning subagent. Give it the full text of the planning brief at the end of this
+prompt, the repository findings, selected framework, frontend, model, credential variable
+names, and selected documentation URLs. Wait for the subagent to finish.
+
+Make sure that the plan preserves each part that already exists. The plan must name the
+credential variables, the Intelligence runtime wiring, the application the project asks
+for, implementation steps, validation steps, and proof steps. It must not contain secret
+values.
+
+Show only the selected framework, frontend, model, planned file changes, validation commands, and proof steps.
+
+If the developer approves the plan, run
+`npx copilotkit@4.8.4 onboard read implementation/build-and-validate`.
+
+If no exact supported path or documentation URL exists, run
+`npx copilotkit@4.8.4 onboard read unsupported/no-validated-path`.
+
+## Planning subagent brief
+
+Everything below the rule is the subagent's prompt. Give it verbatim.
+
+---
+
+# Create the onboarding plan
+
+Use the selected framework, frontend, model, repository findings, and documentation URLs
+from the main coding agent. Fetch every selected URL in one step rather than one after
+another. Do not use remembered CopilotKit instructions.
+
+Name the application the project asks for, and plan that application. Each documentation
+page teaches through one worked example, and that example carries a domain of its own.
+The domain belongs to the page. The project's purpose from the repository findings
+decides what gets built. Where the two differ, the project wins. Where the repository
+never states a purpose, say so in the plan and ask the developer before you adopt the
+domain of an example.
+
+Read only inside the project directory. Answer an API question from the documentation
+URLs you were given, not from another checkout on this machine.
+
+List the required credential variable names. Do not read or return credential values.
+Preserve each agent or frontend that already exists.
+
+Plan the runtime to consume the Intelligence credential. The runtime takes an
+`intelligence` option holding a client built from the project key. A runtime given a
+`runner` option instead is the SSE runtime. It never reads the key, threads are not
+durable, and the Inspector reads the project as locked. The two options cannot be
+combined. Take the constructor from the connect-your-runtime page. Where a framework
+quickstart shows a `runner` option instead, the connect-your-runtime page wins.
+
+Where the SDK requires an application-level value that the repository cannot supply, such
+as an end-user identity for threads, use one clearly marked local placeholder and name what
+production requires instead. Do not stop onboarding to ask the developer for it.
+
+Check whether the existing agent performs unattended side effects, such as paging, sending
+notifications, writing to an external system, or creating tickets. If it does, the new
+conversational surface must not trigger them. Wrap only the reasoning steps, or require an
+explicit developer confirmation before the side effect can run. Name each side effect you
+found and state how the plan avoids it.
+
+If the value of the journey depends on data the project already holds, name that data,
+name where it lives, and name how it reaches the agent. Rendering a list in the DOM does
+not give the agent access to it. An agent wired without the page's data answers from
+entities it invents, and the answer looks correct. Take the frontend-context step from
+the selected documentation. Where no selected page documents it for this framework or
+frontend, record that as a documentation gap rather than guessing the API.
+
+Where that data exists, name the entities the proof compares against: the ids, names, or
+records the project holds and the answer has to reference. Where the outcome references
+no project data, say so in the plan, so that the proof asks for evidence this journey can
+produce.
+
+Create one plan for implementation, validation, and proof. Name each file or area that can
+change. Name the commands that can validate the result.
+Name the commands or user path that prove a real generative-UI round trip.
+
+Keep a production build out of the validation commands. A type check plus the real round
+trip is the proof, and the round trip runs in development mode. Name the production build
+as a follow-up for the developer instead. Never raise a bundle budget or relax a lint rule
+to make a build pass during onboarding.
+
+The type check runs against the project's own configuration. If the project has no
+type-check command, add one that uses the configuration the project already has.
+Do not add compiler strictness the project did not have. Nothing later in the run is
+allowed to weaken type safety, so a stricter gate named here is one the run cannot get
+back out of.
+
+Gather what you need in as few commands as possible. Combine independent reads into one
+command rather than running them one at a time. Split a command only when its result decides
+what you run next.
+
+Return the plan, the URLs that you read, and each documentation gap. Stop after you return
+the findings to the main coding agent.

package/onboarding/prompts/credentials/plan.md

@@ -0,0 +1,38 @@
+# Select the agent framework
+
+Use the repository findings to select the agent framework. Ask the developer only for
+choices that the repository does not show. Do not change application code in this phase.
+Do not read, show, store, or request a secret value.
+
+This release validates six agent frameworks:
+
+| Framework                          | Default vendor |
+| ---------------------------------- | -------------- |
+| LangGraph Python                   | OpenAI         |
+| LangGraph TypeScript               | OpenAI         |
+| ADK                                | Google         |
+| Microsoft Agent Framework (Python) | OpenAI         |
+| Microsoft Agent Framework (.NET)   | GitHub Models  |
+| Mastra                             | OpenAI         |
+
+If the project already has an agent in a listed framework, preserve that framework and
+its model setup. Ask only about choices that remain unknown.
+
+If the project needs an agent, show the options and one recommendation based on repository
+evidence. Match the language the repository already uses. Ask the developer to choose.
+
+Do not offer a framework that is not listed above. Do not port an existing agent to
+another framework. Do not show the internal route.
+
+Use exactly one matching internal route:
+
+1. LangGraph Python: `npx copilotkit@4.8.4 onboard read framework/langgraph-python`
+2. LangGraph TypeScript: `npx copilotkit@4.8.4 onboard read framework/langgraph-typescript`
+3. ADK: `npx copilotkit@4.8.4 onboard read framework/google-adk`
+4. Microsoft Agent Framework Python: `npx copilotkit@4.8.4 onboard read framework/ms-agent-python`
+5. Microsoft Agent Framework .NET: `npx copilotkit@4.8.4 onboard read framework/ms-agent-dotnet`
+6. Mastra: `npx copilotkit@4.8.4 onboard read framework/mastra`
+
+If the project has an agent in another framework, or no listed framework fits, keep the
+developer's current agent and run
+`npx copilotkit@4.8.4 onboard read unsupported/no-validated-path`.

package/onboarding/prompts/framework/google-adk.md

@@ -0,0 +1,41 @@
+# Configure ADK
+
+Preserve an existing ADK model setup. Start with Google for a new agent. Offer another
+vendor only after an exact CopilotKit Markdown page names it. The page must name its
+credential variables and setup steps.
+
+Name the model credential `GOOGLE_API_KEY`. This framework accepts more than one
+spelling, and a scaffold that reaches for a different one looks finished and reads no
+key.
+
+Keep `INTELLIGENCE_API_KEY` separate from model-vendor credentials. Do not read, show,
+store, or request a secret value.
+
+## Documentation
+
+- https://docs.copilotkit.ai/google-adk/quickstart.md
+- https://docs.copilotkit.ai/google-adk/inspector.md
+- https://docs.copilotkit.ai/google-adk/generative-ui/a2ui/fixed-schema.md
+- https://docs.copilotkit.ai/reference/v2/hooks/useAgentContext.md
+
+Fetch all four pages in one step rather than one after another. Sequential fetching
+cost about nine minutes of the first proven journey.
+
+The documentation scope is `google-adk`. A `/adk/` URL answers with a redirect stub
+whose body is the canonical path, so fetch the `google-adk` form.
+
+No page documents the Google ADK side of frontend context. The reference page above
+names the frontend hook, and the agent side of the step is undocumented here. Record
+that missing page as a documentation gap. Do not read the built-in-agent context page
+in its place: that page states no backend work is needed, which holds for the built-in
+agent and not for ADK.
+
+Record the selected framework, vendor, model, required credential variable names, and
+these URLs.
+Do not use remembered CopilotKit instructions.
+
+If the pages support the selection, run
+`npx copilotkit@4.8.4 onboard read frontend/plan`.
+
+If a page does not load or support the selection, run
+`npx copilotkit@4.8.4 onboard read unsupported/no-validated-path`.

package/onboarding/prompts/framework/langgraph-python.md

@@ -0,0 +1,28 @@
+# Configure LangGraph Python
+
+Preserve an existing LangGraph Python model setup. Start with OpenAI for a new agent.
+Offer another vendor only after an exact CopilotKit Markdown page names it. The page must
+name its credential variables and setup steps.
+
+Keep `INTELLIGENCE_API_KEY` separate from model-vendor credentials. Do not read, show,
+store, or request a secret value.
+
+## Documentation
+
+- https://docs.copilotkit.ai/langgraph-python/quickstart.md
+- https://docs.copilotkit.ai/langgraph-python/inspector.md
+- https://docs.copilotkit.ai/langgraph-python/generative-ui/a2ui/fixed-schema.md
+- https://docs.copilotkit.ai/langgraph-python/agent-app-context.md
+
+Fetch all four pages in one step rather than one after another. Sequential fetching
+cost about nine minutes of the first proven journey.
+
+Record the selected framework, vendor, model, required credential variable names, and
+these URLs.
+Do not use remembered CopilotKit instructions.
+
+If the pages support the selection, run
+`npx copilotkit@4.8.4 onboard read frontend/plan`.
+
+If a page does not load or support the selection, run
+`npx copilotkit@4.8.4 onboard read unsupported/no-validated-path`.

package/onboarding/prompts/framework/langgraph-typescript.md

@@ -0,0 +1,28 @@
+# Configure LangGraph TypeScript
+
+Preserve an existing LangGraph TypeScript model setup. Start with OpenAI for a new agent.
+Offer another vendor only after an exact CopilotKit Markdown page names it. The page must
+name its credential variables and setup steps.
+
+Keep `INTELLIGENCE_API_KEY` separate from model-vendor credentials. Do not read, show,
+store, or request a secret value.
+
+## Documentation
+
+- https://docs.copilotkit.ai/langgraph-typescript/quickstart.md
+- https://docs.copilotkit.ai/langgraph-typescript/inspector.md
+- https://docs.copilotkit.ai/langgraph-typescript/generative-ui/a2ui/fixed-schema.md
+- https://docs.copilotkit.ai/langgraph-typescript/agent-app-context.md
+
+Fetch all four pages in one step rather than one after another. Sequential fetching
+cost about nine minutes of the first proven journey.
+
+Record the selected framework, vendor, model, required credential variable names, and
+these URLs.
+Do not use remembered CopilotKit instructions.
+
+If the pages support the selection, run
+`npx copilotkit@4.8.4 onboard read frontend/plan`.
+
+If a page does not load or support the selection, run
+`npx copilotkit@4.8.4 onboard read unsupported/no-validated-path`.

package/onboarding/prompts/framework/mastra.md

@@ -0,0 +1,58 @@
+# Configure Mastra
+
+Preserve an existing Mastra model setup. Start with OpenAI for a new agent. Offer
+another vendor only after an exact CopilotKit Markdown page names it. The page must name
+its credential variables and setup steps.
+
+Name the model credential `OPENAI_API_KEY`.
+
+Keep `INTELLIGENCE_API_KEY` separate from model-vendor credentials. Do not read, show,
+store, or request a secret value.
+
+`mastra dev` loads the `.env` beside the project it serves and does not look in a
+parent directory. When one credential file serves more than one part of the repository,
+name the path in the dev script as `mastra dev --env <path>` rather than relying on a
+search.
+
+The dev server serves port 4111 and puts a web console at `/` on that same port. A
+request to `/` answers 200 with HTML whether or not an agent exists, so read
+`/api/agents` to confirm which agent is served.
+
+That console runs any agent the Mastra instance registers, with that agent's full
+tool set, and the API behind it takes
+`POST /api/agents/{agentId}/tools/{toolId}/execute`, which invokes one tool with no
+model and no credential. Neither surface asks for authentication. Tool gating done
+at the CopilotKit runtime governs the runtime's route and does not reach this port.
+Where the project restricts which tools reach a browser, say in the summary that
+the agent port is a second, ungated entrance to the same tools.
+
+The dev server binds every interface unless it is told not to, while the banner it
+prints, the `.mastra/dev.lock` it writes and the framework's own documentation all
+say `localhost`. Bind it to loopback: `MASTRA_HOST=127.0.0.1` on the dev command
+when the agent is the developer's existing code, or `server: { host: '127.0.0.1' }`
+on a Mastra instance this run creates. Declare a `server.port` beside it only if
+the run does not also rely on `PORT`, which it overrides.
+
+If the project already runs the agent as its own service, reach it where it runs. The
+quickstart shows the agent inside the frontend, and moving a running agent there deletes
+what the developer had.
+
+## Documentation
+
+- https://docs.copilotkit.ai/mastra/quickstart.md
+- https://docs.copilotkit.ai/mastra/inspector.md
+- https://docs.copilotkit.ai/mastra/generative-ui/a2ui/fixed-schema.md
+- https://docs.copilotkit.ai/mastra/agent-app-context.md
+
+Fetch all four pages in one step rather than one after another. Sequential fetching
+cost about nine minutes of the first proven journey.
+
+Record the selected framework, vendor, model, required credential variable names, and
+these URLs.
+Do not use remembered CopilotKit instructions.
+
+If the pages support the selection, run
+`npx copilotkit@4.8.4 onboard read frontend/plan`.
+
+If a page does not load or support the selection, run
+`npx copilotkit@4.8.4 onboard read unsupported/no-validated-path`.