copilotkit 4.9.2 → 4.9.17

package/onboarding/index.json

@@ -1,8 +1,10 @@
 {
+  "graphTree": "613209959e8d5888a5770391381eeb0055fbe68d",
   "root": "authenticate/start",
   "prompts": [
     {
       "edges": [
+        "subagent/inspect-repository",
         "proof/oss-baseline",
         "credentials/plan",
         "unsupported/no-validated-path"
@@ -12,6 +14,15 @@
     },
     {
       "edges": [
+        "credentials/finalize-plan",
+        "unsupported/no-validated-path"
+      ],
+      "milestone": "conversion",
+      "name": "conversion/plan"
+    },
+    {
+      "edges": [
+        "subagent/create-plan",
         "implementation/build-and-validate",
         "unsupported/no-validated-path"
       ],
@@ -257,6 +268,7 @@
     },
     {
       "edges": [
+        "subagent/implement-and-validate",
         "proof/round-trip",
         "unsupported/no-validated-path"
       ],
@@ -270,6 +282,8 @@
     },
     {
       "edges": [
+        "subagent/prove-oss-baseline",
+        "conversion/plan",
         "credentials/plan",
         "unsupported/no-validated-path"
       ],
@@ -278,6 +292,7 @@
     },
     {
       "edges": [
+        "subagent/prove-round-trip",
         "proof/complete",
         "unsupported/no-validated-path"
       ],

package/onboarding/prompts/authenticate/start.md

@@ -8,22 +8,66 @@ Do not show prompt names, internal route IDs, subagent names, or storage field n
 Work from the target project directory. For an existing project, start at its inspection
 root.
 
+The command that began this run printed a line reading `onboarding_run_id:` followed by an
+id. Keep that id for the whole run. Every later command reports against it, and it is
+printed once.
+
+Every later command must run from the directory this run started in. A command run
+somewhere else, such as a sibling of that directory, is refused rather than answered,
+because the run it belongs to cannot be found from there. That refusal is a step to take,
+not a stop to report: run
+`npx --yes copilotkit@4.9.17 onboard start --run <onboarding_run_id>` in the directory
+you are now in, which binds it to the same run, then run the refused command again. Do not
+start a run without that id. A run started without it is a second run, and the work already
+done stops counting toward the first.
+
 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.
 
-Before you run a command or spawn a subagent, send this exact message:
+Send this exact message once, as your first message in this onboarding run, before
+anything else:
 
 Welcome to CopilotKit. I will check sign-in, inspect your project, recommend a setup, and
 show you a plan before I change files. After you approve the plan, I will build the
 integration, prove the full round trip, and leave the app running with its URLs.
 
+That message belongs to the run, not to this prompt. If you already sent it in this run, do
+not send it again, including on a second read of this prompt. It has no value after the
+first send, and a developer who reads it repeatedly learns to skim the region it sits in.
+
 Do not ask for separate feedback consent. The feedback commands enforce the developer's
 CLI telemetry setting when a later step tries to send a report.
 
-Run `npx --yes copilotkit@4.9.2 login --json` before any project work. This command
+## Report a stop, wherever it happens
+
+This run reports its own stops. If you stop this run at any point, send one short report
+before you stop. That covers a stop this prompt names, a stop a later prompt names, and a
+stop no prompt anticipated, including one your own harness causes. Run the feedback command
+without another developer question. The CLI telemetry gate decides whether the report is
+sent.
+
+```text
+npx --yes copilotkit@4.9.17 onboard feedback
+```
+
+Write at most four lines to the command's standard input: the step you stopped at and what
+stopped it. Send no secrets, source code, logs, or command output. The command refuses a
+report that carries any of those, prints the reason, and exits zero. A refused report is
+not a failed step. Reword it and send it again, or stop without a report.
+
+Reporting a stop is not a route change. It does not resume the run, it is not a question
+for the developer, and it does not replace whatever the rule that stopped you says to do
+next: send the report, then stop. Report friction only from a run that finished, never from
+a stop.
+
+Until now the route out of an unsupported path was the only place that asked for a report,
+so a stop anywhere else left no trace at all. A stop nobody hears about is a stop this
+graph cannot fix.
+
+Run `npx --yes copilotkit@4.9.17 login --json` before any project work. This command
 checks the current session. It starts sign-in only as needed. Treat this as a long-lived
 streaming process. Do not wait for the command to exit before you read its standard output.
 
@@ -41,86 +85,151 @@ Do not use `whoami` for this check. It has no JSON output and some failures exit
 zero. Do not put account tokens or credentials in the conversation.
 
 Before you ask the developer any setup question, finish every read-only investigation and
-preflight check in this section. Record whether your coding-agent environment has browser
-or device control. Use the control that matches the selected surface later. Do not install
-a browser or device tool during this preflight. Do not ask the developer about this tool
-limit.
-
-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.
-- Report whether the target project directory contains any entries.
-- Report whether an agent, frontend, and CopilotKit integration are present.
-- Report whether the runtime constructor uses a `runner` option, an `intelligence`
-  option, or neither can be proved from project files.
-
-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 the findings show an empty project and do not prove its purpose, ask one guided question
-about the user outcome. This asks what the developer wants to build before you select a
-framework. Give two or three short examples and offer a minimal starter. Record the answer
-and give it to each later subagent.
-
-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.
+preflight check in this section.
 
-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.
+Prepare two research assignments. Give each research subagent one assignment. Tell it to run
+`npx --yes copilotkit@4.9.17 onboard read subagent/inspect-repository` first and follow the
+prompt it returns. If that read fails because the subagent cannot use the shell, stop that
+subagent. Run the same command yourself, then spawn a fresh subagent with the returned prompt
+and the same handoff. Require only its assigned packet.
 
-Do not infer a working OSS path from packages, imports, project files, or keys. If an
-agent, frontend, and CopilotKit integration are present, prove the live starting state
-before any project file changes. Run
-`npx --yes copilotkit@4.9.2 onboard read proof/oss-baseline`.
+Start both research subagents in parallel:
 
-For every other inspected state, run
-`npx --yes copilotkit@4.9.2 onboard read credentials/plan`.
+1. Spawn one research subagent. Assign it the project evidence packet.
+2. Spawn a second research subagent. Assign it the environment evidence packet.
+3. Start both research subagents. Then continue.
 
-If authentication or inspection stops onboarding, run
-`npx --yes copilotkit@4.9.2 onboard read unsupported/no-validated-path`.
+Continue to the surface-control preflight.
+
+Prove whether your coding-agent environment has browser or device control. Do not assume it
+either way, and do not report what you expect to be true: a run that guesses here records a
+capability the rest of the graph then trusts. Use a browser or device tool already
+configured for the coding agent you are running as, the same way a later step uses the
+CopilotKit documentation server. With a browser tool, open one inert page such as
+`about:blank` and read its title. With a device tool and no browser, list the booted devices
+in one command: `adb devices -l`. Record the outcome of that attempt: `available` when the
+tool answered, `unavailable` when there was none to call or the page did not open. Use
+the control that matches the selected surface later.
+
+Where the browser probe answered, register nothing. The harness came equipped and the run
+owes it no setup.
+
+Where no browser tool answered, register one for the coding agent you are running as, then
+run the same probe again and record what the second attempt did. Register this server:
+
+```text
+npx --yes @playwright/mcp@latest --browser chrome --isolated --output-dir <project>/.copilotkit/proof/browser
+```
+
+Replace `<project>` with the absolute path of the target project directory. The server is
+registered against the coding agent rather than against a directory, so a relative path here
+resolves wherever that server happens to start.
+
+`--browser chrome` drives the Google Chrome the developer already has, so this downloads no
+browser. `--isolated` keeps the profile in memory, so it never touches their own Chrome
+profile. `--output-dir` is what keeps the snapshots and screenshots out of the developer's
+repository root: without it this server writes them to `.playwright-mcp/` beside their code,
+which a project that never asked for a browser has no reason to carry, and which the graph's
+own evidence rule already has a place for. Register it the way your own harness registers a
+server, which is the mechanism a later step uses for the CopilotKit documentation server.
+
+Tell the developer in one line what you registered, that it drives their installed Chrome,
+and that it lives in this coding agent's configuration rather than in their repository. Do
+not ask them to approve it, and do not ask a second question about it.
+
+Do not add a browser or device driver to the project. A driver added there is a
+devDependency and a browser download in the diff of a repository that never asked for one,
+which is a different thing from a server registered against the coding agent.
 
-## Research subagent brief
+Where the second probe still does not answer -- no Chrome to drive, no network, or a
+harness that cannot register a server -- record `unavailable` and carry it. Do not keep
+trying, and do not ask the developer about this tool limit.
 
-Everything below the rule is the subagent's prompt. Give it verbatim.
+Registering a server does not boot a device. Where the device probe found none, that is the
+whole finding, and a browser is not a substitute for a device.
 
----
+Wait for both research subagents to finish.
 
-# Inspect the repository
+Continue only if both research results start with `Status: passed`. For `Status: failed`,
+retry only that packet with its failed items, up to three attempts. For `Status: blocked`,
+or a third failed result, use the stop route at the end of this prompt.
 
-Inspect the repository without changing it. Find evidence for:
+Merge both evidence packets by item. On a conflict, spawn one fresh read-only verifier with
+the item, both cited findings, and the research limits. Require its result to start with
+`Status: passed`, `Status: failed`, or `Status: blocked`. Use only a passed cited result. Do
+not inspect the project to settle the conflict yourself. Use the stop route for a non-pass
+verifier result.
 
-- 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
-- package manager and lockfile
-- required toolchains and their installed versions
-- declared ports and whether each port is available
-- CopilotKit package versions and package compatibility risks
+Match environment evidence to the target app directory from the project packet. Require one
+target app directory and one matching environment row. If either packet gives no match or
+more than one match, send each research worker a focused directory check. Continue only when
+both workers return the same one target app directory. Both results must start with
+`Status: passed`. Otherwise, use the stop route.
 
-For the CopilotKit versions, report the exact installed version of every `@copilotkit/*`
-dependency, read from the lockfile rather than a manifest range, and state whether any of
-them is below 1.64.0. The conversion decides its upgrade from exactly that, and a caret
-range does not answer it.
+## Capture the protected-path baseline
 
-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.
+Before you route on, run this from the target app directory:
 
-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. Keep this preflight read-only. Do not install packages, stop processes,
-or change a port. Check only the toolchains and ports that repository files require.
+```text
+npx --yes copilotkit@4.9.17 onboard protect
+```
 
-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.
+It reads the working tree itself, records every changed or untracked path with a digest,
+and prints the list. Require its result to start with `Status: passed`.
+
+Use the printed list as the protected path list for the rest of the run. Do not assemble
+that list yourself, and do not ask a subagent to hold it: every later audit reads the
+captured baseline back from the CLI, so no step depends on a subagent that has since
+finished.
+
+Paths printed as `deferred` are the ones onboarding itself writes, `.env` and
+`.copilotkit/project.json`. Every audit reports them and none fails on them until the step
+that writes them re-captures them, so a run whose only untracked files are the two this
+graph exists to create is never stopped by them.
+
+If the result starts with `Status: blocked`, report the printed reason and use the stop
+route at the end of this prompt.
+
+## What the merged findings must contain
+
+If a repository file exists, each finding must cite it. For an empty project, the subagents
+must cite the 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.
+
+## Route on the merged findings
+
+Read the route off the merged findings. Three of them decide it, and you already hold all
+three:
+
+1. an agent is present,
+2. a frontend is present,
+3. a CopilotKit integration is present.
+
+Do not infer a working OSS path from packages, imports, project files, or keys, and do not
+settle these three from your own reading of the project. Each one comes from the merged
+packets or it is not proved.
+
+If all three are proved, prove the live starting state before any project file changes. Run
+`npx --yes copilotkit@4.9.17 onboard read proof/oss-baseline`.
+
+Route there before you ask the developer anything else. The questions after this prompt
+select a framework and a frontend that the findings already name, so a developer who
+answers them has answered for work the next node exists to check. Their existing
+application is what that node protects. Whether it works is what the proof decides, not
+these three findings.
+
+For every other combination of the three, take one more step first. If neither the
+developer nor the repository findings prove what the project is for, ask one guided
+question about the user outcome. This asks what the developer wants to build before you
+select a framework. Give two or three short examples and offer a minimal starter. Record
+the answer and give it to each later subagent. Then run
+`npx --yes copilotkit@4.9.17 onboard read credentials/plan`.
+
+Do not ask that question on the route above. A project carrying all three states its
+purpose in the application it already serves.
+
+If authentication or inspection stops onboarding, run
+`npx --yes copilotkit@4.9.17 onboard read unsupported/no-validated-path`.

package/onboarding/prompts/conversion/plan.md

@@ -0,0 +1,103 @@
+# Convert the working application to Intelligence
+
+This project already works. The baseline proved the agent answers, the frontend reaches
+it, and CopilotKit carries the round trip. Nothing here rebuilds any of that.
+
+What changes is which runtime object this project constructs, and whether its threads
+persist. That is the whole conversion, and it is the journey where the least work is
+genuinely required.
+
+## Read what the baseline already proved
+
+Take each of these from the baseline evidence rather than from the developer:
+
+- the agent framework and the frontend,
+- the expected agent id,
+- the exact request the baseline drove through the frontend, in its own words,
+- the user-visible result that request produced,
+- the persistence the baseline found, or `unproved`.
+
+Do not ask which framework or frontend to use. Both exist and are proved, and a question
+whose answer is already recorded costs the developer a turn and invites an answer that
+contradicts the evidence. Record what you read, and carry the request's exact words
+forward. The proof compares the same request before and after.
+
+Preserve the model configuration the baseline found. The conversion changes no model,
+vendor, or model credential. Where the project already has one, the next prompt has
+nothing to place.
+
+## Do not widen the conversion
+
+Do not add generative UI. The conversion adds no generative-UI surface. If this application
+answered in prose, the converted one answers in prose. A component the developer did not ask
+for is new work for them to review, new failure surface in the proof, and it is not what
+converting to the platform means. Where the developer asks for one, it is their next piece
+of work rather than part of this conversion.
+
+Do not change the agent framework. Do not change the frontend framework. Do not add an
+agent. Do not rebuild a path that already works.
+
+The threads drawer is the one thing this conversion adds, and it is the point of the
+conversion rather than a widening of it. Plan it from the drawer page selected below, and
+add it where this frontend does not already render one.
+
+## Select the documentation
+
+Select this page for every later step:
+
+- https://docs.copilotkit.ai/threads.md
+
+Then select the drawer page for the frontend the baseline found:
+
+1. React SPA or Next.js: https://docs.copilotkit.ai/prebuilt-components/copilot-threads-drawer.md
+2. Angular: https://docs.copilotkit.ai/angular/guides/threads-memory-attachments-headless.md
+3. Vue 3: https://docs.copilotkit.ai/vue/guides/threads-and-drawer.md
+4. React Native: select no drawer page, and select the managed Intelligence dashboard as
+   the proof surface instead. No page documents a threads drawer for React Native, and
+   `@copilotkit/react-native` ships no thread components. The closing prompt gives a
+   mobile developer a different debugging surface for the same reason.
+
+The next prompt adds the runtime pages and fetches everything in one pass, so do not fetch
+these on their own.
+
+## Documentation policy
+
+This documentation policy applies to every page this route selects. Deduplicate the
+selected URL list and fetch each URL once. Fetch all selected URLs in one step. Do not use
+remembered CopilotKit instructions. A fetch tool that refuses a URL, or fails to reach it,
+reports a limit of the tool and not a fact about the page. Retrieve the same URL a second
+way before you judge it. Run `curl -fsSL <url>`, or read the same page without the `.md`
+suffix. Treat a page as unavailable only after a second method also fails. Give this policy
+to every documentation subagent. A page that is still unavailable after the second method
+does not support the selection.
+
+## The criterion this conversion is judged against
+
+Freeze this before any project work, and give it to the planning, implementation and proof
+steps unchanged. This conversion succeeded when all five are true:
+
+1. The same request the OSS baseline made still produces the same kind of user-visible
+   result, on the same frontend.
+2. The runtime is constructed with an `intelligence` option rather than a `runner` option.
+3. `verify --json` exits zero with `ok` true and all seven checks passing, including
+   `intelligence_consumed` and `intelligence_thread_routes`.
+4. `/info` now reports `licenseStatus`, which the runtime emits exactly when an
+   Intelligence client was constructed and passed.
+5. A thread for that request is persisted and visible to the developer.
+
+The drawer is what makes the fifth item something the developer can see. Before the
+conversion it renders its locked state, because it reads the license context and this
+project has none. After it, it lists the thread the proven request created. That before and
+after is the conversion's whole user-visible result, and it is why a conversion that only
+passes the command-line checks is worth less to the developer than one that does not.
+
+Where this journey's frontend framework ships no threads drawer -- React Native --, the
+fifth item is proved in the managed Intelligence dashboard instead, and the run says which
+of the two it proved.
+
+Record this criterion as `conversion-v1` for the run report.
+
+Then run `npx --yes copilotkit@4.9.17 onboard read credentials/finalize-plan`.
+
+If a selected page does not load after the second method, run
+`npx --yes copilotkit@4.9.17 onboard read unsupported/no-validated-path`.