copilotkit 4.9.4 → 4.9.24

package/onboarding/index.json

@@ -1,9 +1,10 @@
 {
-  "graphTree": "1c6963da1f044e99a35706e1f6ba533c2ad835c2",
+  "graphTree": "8619678c9fde3386c7b4986b3241775007971075",
   "root": "authenticate/start",
   "prompts": [
     {
       "edges": [
+        "subagent/inspect-repository",
         "proof/oss-baseline",
         "credentials/plan",
         "unsupported/no-validated-path"
@@ -13,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"
       ],
@@ -258,6 +268,7 @@
     },
     {
       "edges": [
+        "subagent/implement-and-validate",
         "proof/round-trip",
         "unsupported/no-validated-path"
       ],
@@ -271,6 +282,8 @@
     },
     {
       "edges": [
+        "subagent/prove-oss-baseline",
+        "conversion/plan",
         "credentials/plan",
         "unsupported/no-validated-path"
       ],
@@ -279,6 +292,7 @@
     },
     {
       "edges": [
+        "subagent/prove-round-trip",
         "proof/complete",
         "unsupported/no-validated-path"
       ],

package/onboarding/prompts/authenticate/start.md

@@ -8,6 +8,19 @@ 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.24 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
@@ -28,7 +41,33 @@ first send, and a developer who reads it repeatedly learns to skim the region it
 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.4 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.24 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.24 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.
 
@@ -48,6 +87,20 @@ 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.
 
+Prepare two research assignments. Give each research subagent one assignment. Tell it to run
+`npx --yes copilotkit@4.9.24 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.
+
+Start both research subagents in parallel:
+
+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.
+
+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
@@ -95,77 +148,88 @@ trying, and do not ask the developer about this tool limit.
 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.
 
-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. Wait for the
-subagent to finish.
+Wait for both research subagents to finish.
+
+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.
+
+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.
+
+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.
 
-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.
+## Capture the protected-path baseline
 
-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.
+Before you route on, run this from the target app directory:
+
+```text
+npx --yes copilotkit@4.9.24 onboard protect
+```
+
+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.
 
-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.4 onboard read proof/oss-baseline`.
+## 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.24 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.24 onboard read credentials/plan`.
 
-For every other inspected state, run
-`npx --yes copilotkit@4.9.4 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.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
-- the target app or runtime directory that owns `.env` and the CopilotKit setup
-- whether the target project directory contains any entries
-- any existing agent framework and frontend
-- current CopilotKit integration and configuration, including whether
-  `.copilotkit/project.json` has `projectId`, `projectSlug`, and `clerkOrgId`
-- authentication boundaries
-- names of required credential variables and whether `.env` has a non-empty
-  `INTELLIGENCE_API_KEY`
-- retain the `.env` modification time for a later comparison without returning it
-- package manager and lockfile
-- required toolchains and their installed versions
-- declared ports and whether each port is available
-- whether the runtime constructor uses a `runner` option, an `intelligence` option, or
-  neither can be proved from project files
-- CopilotKit package versions and package compatibility risks
-
-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.
-
-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. 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.
-
-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. For `.env` and `.copilotkit/project.json`
-checks, return only paths, presence checks, and missing field names. 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.
+`npx --yes copilotkit@4.9.24 onboard read unsupported/no-validated-path`.

package/onboarding/prompts/conversion/plan.md

@@ -0,0 +1,113 @@
+# 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. No page documents a threads drawer for React
+   Native, and `@copilotkit/react-native` ships no thread components, so the fifth
+   criterion below is proved on the command line instead. 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 lists nothing, because it reads the entitlement the runtime reports and an
+OSS runtime reports 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.
+
+A managed Intelligence project needs no license token. The entitlement the drawer reads
+comes from the project API key this run already configured, resolved by the runtime
+against the managed platform. Minting a token with `copilotkit license create` is not part
+of this journey, and a drawer that lists nothing is not a reason to mint one. License
+tokens stay a self-hosted concern.
+
+Where this journey's frontend framework ships no threads drawer -- React Native --, the
+fifth item is proved by `npx --yes copilotkit@4.9.24 verify --round-trip`, which sends a
+real request and reads the answer back off the thread it landed on. The run says which of
+the two it proved. Do not send a run to the managed Intelligence dashboard to prove this.
+An authenticated browser session at a hosted dashboard is the one thing an agent-driven run
+cannot produce, so a criterion that asks for one can never be met on this route.
+
+Record this criterion as `conversion-v1` for the run report.
+
+Then run `npx --yes copilotkit@4.9.24 onboard read credentials/finalize-plan`.
+
+If a selected page does not load after the second method, run
+`npx --yes copilotkit@4.9.24 onboard read unsupported/no-validated-path`.