copilotkit 4.10.1 → 4.12.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (80) hide show
  1. package/LICENSE +11 -0
  2. package/README.md +153 -17
  3. package/cli-build-info.json +8 -8
  4. package/index.js +5104 -4673
  5. package/onboarding/index.json +9 -2
  6. package/onboarding/prompts/authenticate/start.md +35 -19
  7. package/onboarding/prompts/conversion/plan.md +3 -3
  8. package/onboarding/prompts/credentials/finalize-plan.md +37 -27
  9. package/onboarding/prompts/credentials/plan.md +20 -20
  10. package/onboarding/prompts/credentials/settle-credentials.md +57 -25
  11. package/onboarding/prompts/credentials/write-plan.md +7 -7
  12. package/onboarding/prompts/fallback/best-effort.md +9 -8
  13. package/onboarding/prompts/feature/a2ui/implement.md +7 -7
  14. package/onboarding/prompts/feature/a2ui/proof.md +6 -6
  15. package/onboarding/prompts/feature/a2ui/start.md +10 -8
  16. package/onboarding/prompts/feature/blocked-by-plan.md +32 -0
  17. package/onboarding/prompts/feature/channels/implement.md +9 -9
  18. package/onboarding/prompts/feature/channels/proof.md +6 -6
  19. package/onboarding/prompts/feature/channels/start.md +20 -15
  20. package/onboarding/prompts/feature/chat-suggestions/implement.md +7 -7
  21. package/onboarding/prompts/feature/chat-suggestions/proof.md +6 -6
  22. package/onboarding/prompts/feature/chat-suggestions/start.md +10 -8
  23. package/onboarding/prompts/feature/complete.md +1 -1
  24. package/onboarding/prompts/feature/learning/implement.md +73 -14
  25. package/onboarding/prompts/feature/learning/proof.md +10 -9
  26. package/onboarding/prompts/feature/learning/start.md +61 -7
  27. package/onboarding/prompts/feature/open-generative-ui/implement.md +7 -7
  28. package/onboarding/prompts/feature/open-generative-ui/proof.md +6 -6
  29. package/onboarding/prompts/feature/open-generative-ui/start.md +10 -8
  30. package/onboarding/prompts/feature/realtime-sync/implement.md +8 -8
  31. package/onboarding/prompts/feature/realtime-sync/proof.md +6 -6
  32. package/onboarding/prompts/feature/realtime-sync/start.md +9 -7
  33. package/onboarding/prompts/feature/rich-threads/implement.md +9 -9
  34. package/onboarding/prompts/feature/rich-threads/proof.md +6 -6
  35. package/onboarding/prompts/feature/rich-threads/start.md +9 -7
  36. package/onboarding/prompts/feature/stop.md +6 -6
  37. package/onboarding/prompts/feature/voice/implement.md +7 -7
  38. package/onboarding/prompts/feature/voice/proof.md +6 -6
  39. package/onboarding/prompts/feature/voice/start.md +10 -8
  40. package/onboarding/prompts/framework/ag2.md +2 -2
  41. package/onboarding/prompts/framework/agno.md +2 -2
  42. package/onboarding/prompts/framework/built-in.md +2 -2
  43. package/onboarding/prompts/framework/claude-sdk-python.md +2 -2
  44. package/onboarding/prompts/framework/claude-sdk-typescript.md +2 -2
  45. package/onboarding/prompts/framework/crewai-flows.md +2 -2
  46. package/onboarding/prompts/framework/deep-agents.md +2 -2
  47. package/onboarding/prompts/framework/google-adk.md +2 -2
  48. package/onboarding/prompts/framework/langgraph-fastapi.md +2 -2
  49. package/onboarding/prompts/framework/langgraph-python.md +2 -2
  50. package/onboarding/prompts/framework/langgraph-typescript.md +2 -2
  51. package/onboarding/prompts/framework/llamaindex.md +2 -2
  52. package/onboarding/prompts/framework/mastra.md +2 -2
  53. package/onboarding/prompts/framework/ms-agent-dotnet.md +2 -2
  54. package/onboarding/prompts/framework/ms-agent-harness-dotnet.md +2 -2
  55. package/onboarding/prompts/framework/ms-agent-python.md +2 -2
  56. package/onboarding/prompts/framework/pydantic-ai.md +2 -2
  57. package/onboarding/prompts/framework/strands-python.md +2 -2
  58. package/onboarding/prompts/framework/strands-typescript.md +2 -2
  59. package/onboarding/prompts/frontend/angular.md +5 -5
  60. package/onboarding/prompts/frontend/nextjs.md +4 -4
  61. package/onboarding/prompts/frontend/plan.md +17 -12
  62. package/onboarding/prompts/frontend/react-native.md +2 -2
  63. package/onboarding/prompts/frontend/react-spa.md +2 -2
  64. package/onboarding/prompts/frontend/vue.md +2 -2
  65. package/onboarding/prompts/implementation/build-and-validate.md +35 -18
  66. package/onboarding/prompts/proof/complete.md +26 -17
  67. package/onboarding/prompts/proof/oss-baseline.md +5 -5
  68. package/onboarding/prompts/proof/round-trip.md +16 -15
  69. package/onboarding/prompts/research/gather.md +55 -9
  70. package/onboarding/prompts/research/route.md +30 -10
  71. package/onboarding/prompts/starter/clone.md +6 -6
  72. package/onboarding/prompts/stopped/run-failed.md +32 -3
  73. package/onboarding/prompts/subagent/create-plan.md +7 -1
  74. package/onboarding/prompts/subagent/implement-and-validate.md +2 -1
  75. package/onboarding/prompts/subagent/inspect-repository.md +43 -16
  76. package/onboarding/prompts/subagent/prove-oss-baseline.md +1 -1
  77. package/onboarding/prompts/subagent/prove-round-trip.md +52 -18
  78. package/onboarding/prompts/unsupported/no-validated-path.md +4 -4
  79. package/package.json +4 -3
  80. package/release/release-tool.js +1 -1
@@ -9,7 +9,7 @@ sends the run down one path.
9
9
  Before you route on, run this from the target app directory:
10
10
 
11
11
  ```text
12
- npx --yes copilotkit@4.10.1 onboard protect
12
+ npx --yes copilotkit@4.12.0 onboard protect
13
13
  ```
14
14
 
15
15
  It reads the working tree itself, records every changed or untracked path with a digest,
@@ -37,6 +37,27 @@ The findings must cover what the project is for, the agent, frontend, CopilotKit
37
37
  authentication, credential names, and validation path. Do not ask the developer for facts
38
38
  that the repository answers.
39
39
 
40
+ ## What the CLI proposed for the framework and frontend
41
+
42
+ `onboard inspect` matched the project's manifests against the framework and frontend sets
43
+ this graph serves, and its `detection` block carries the result with the dependency and
44
+ directory behind each answer. Read it as a proposal.
45
+
46
+ - `match` names the one slug that fits. Confirm it against the findings before you use it.
47
+ - `matched` holds more than one slug where more than one fits. `langgraph-python` and
48
+ `langgraph-fastapi` are two ways of serving one framework and no dependency tells them
49
+ apart, so pick by how the agent is actually served.
50
+ - `match: null` with an empty `matched` means the CLI placed nothing. This is never a
51
+ stop, and never a reason to route out on its own. It says only that no dependency
52
+ matched. Whether the project can be onboarded is your judgment, not its.
53
+ - `unmatched` names the dependencies it did not place. Use them as evidence for what the
54
+ project runs.
55
+
56
+ Detection proposes and you dispose. Keep the documentation-gap exception exactly as it is:
57
+ an agent framework outside this set that speaks AG-UI is still yours to recognize and
58
+ route to best effort. Where your reading disagrees with the proposal, record your own
59
+ answer and say that the two disagreed.
60
+
40
61
  ## Route on the merged findings
41
62
 
42
63
  Read the route off the merged findings. Three of them decide it, and you already hold all
@@ -51,7 +72,7 @@ settle these three from your own reading of the project. Each one comes from the
51
72
  packets or it is not proved.
52
73
 
53
74
  If all three are proved, prove the live starting state before any project file changes. Run
54
- `npx --yes copilotkit@4.10.1 onboard read proof/oss-baseline`.
75
+ `npx --yes copilotkit@4.12.0 onboard read proof/oss-baseline`.
55
76
 
56
77
  Route there before you ask the developer anything else. The questions after this prompt
57
78
  select a framework and a frontend that the findings already name, so a developer who
@@ -64,18 +85,17 @@ developer nor the repository findings prove what the project is for, ask one gui
64
85
  question about the user outcome. This asks what the developer wants to build before you
65
86
  select a framework. Give two or three short examples and offer a minimal starter. Record
66
87
  the answer and give it to each later subagent. Then run
67
- `npx --yes copilotkit@4.10.1 onboard read credentials/plan`.
88
+ `npx --yes copilotkit@4.12.0 onboard read credentials/plan`.
68
89
 
69
90
  Do not ask that question on the route above. A project carrying all three states its
70
91
  purpose in the application it already serves.
71
92
 
72
- Do not ask it when the target directory holds no project either. A greenfield run clones a starter
73
- the CLI ships, and that starter arrives carrying a working application of its own. The
74
- answer cannot change which starter lands, because the starter follows from the framework
75
- and frontend the developer selects next. Asking spends a turn on a decision the run has
76
- already made, and then names a purpose the cloned code does not serve. Take the same read
77
- named above without asking, and let the starter state the domain.
93
+ Do not ask it when the target directory holds no project either.
94
+ The frontend they pick next decides the starter.
95
+ Slack and Microsoft Teams are choices at that step.
96
+ A purpose question here names a domain before that choice.
97
+ Take the same read named above without asking.
78
98
 
79
99
  If authentication or inspection stops onboarding, run
80
- `npx --yes copilotkit@4.10.1 onboard read stopped/run-failed`. Neither says anything
100
+ `npx --yes copilotkit@4.12.0 onboard read stopped/run-failed`. Neither says anything
81
101
  about whether this project's stack is supported, which is not yet known at this point.
@@ -37,7 +37,7 @@ selected pair is not in the table, or the directory name is not valid, stop the
37
37
  Do not run `init`. Treat this result as a failed shortcut and follow the final failure
38
38
  instruction in this prompt.
39
39
 
40
- If the developer did not name an Intelligence project, create one for the app being
40
+ If the developer did not name a project, create one for the app being
41
41
  cloned. This directory is new, so no existing project is already its own: take the project
42
42
  name from the target directory name derived above, and ask the developer to confirm it or
43
43
  give another. Do not list the projects in the organization. If no developer answers, use
@@ -46,7 +46,7 @@ the derived name.
46
46
  Only if the developer asks for an existing project, or asks to see the projects they have,
47
47
  read the choices:
48
48
 
49
- `npx --yes copilotkit@4.10.1 project list --json`
49
+ `npx --yes copilotkit@4.12.0 project list --json`
50
50
 
51
51
  Then ask which one to use. Do not order the projects by creation time. If the developer
52
52
  already gave this answer, do not ask again. Do not read a secret value. Do not show or
@@ -56,7 +56,7 @@ Run the command from the parent directory. Do not inspect another entry in the p
56
56
  directory. Replace each placeholder with the recorded value. Do not run a placeholder as
57
57
  a shell argument.
58
58
 
59
- `npx --yes copilotkit@4.10.1 init --name <project-name> --framework <framework-id> --channel none --no-banner --create <name> --install`
59
+ `npx --yes copilotkit@4.12.0 init --name <project-name> --framework <framework-id> --channel none --no-banner --create <name> --install`
60
60
 
61
61
  Pass the confirmed name to both `--name` and `--create`: the app directory and its
62
62
  Intelligence project take the same name here. If the developer names an existing project,
@@ -72,7 +72,7 @@ account. The command does not need terminal input.
72
72
  Report the clone before you inspect anything:
73
73
 
74
74
  ```text
75
- npx --yes copilotkit@4.10.1 onboard checkpoint --phase starter-cloned
75
+ npx --yes copilotkit@4.12.0 onboard checkpoint --phase starter-cloned
76
76
  ```
77
77
 
78
78
  This is its own step, not an aside. A run that clones and then goes quiet is
@@ -82,10 +82,10 @@ separates them.
82
82
  Do not rebuild the starter by hand. Then inspect only the generated
83
83
  paths inside the target directory. Record the files, install result, project connection,
84
84
  and validation commands. Then run
85
- `npx --yes copilotkit@4.10.1 onboard read proof/round-trip`.
85
+ `npx --yes copilotkit@4.12.0 onboard read proof/round-trip`.
86
86
 
87
87
  If the command fails, report its exact error and do not claim that the starter is ready.
88
88
  Then run
89
- `npx --yes copilotkit@4.10.1 onboard read stopped/run-failed`. The starter is one this
89
+ `npx --yes copilotkit@4.12.0 onboard read stopped/run-failed`. The starter is one this
90
90
  graph ships and the stack was chosen from its own supported list, so a command that
91
91
  returned an error is a run that broke, not a setup this release does not support.
@@ -23,13 +23,42 @@ Say what the developer has now. Name the processes still running and the files t
23
23
  changed, so they can carry on by hand or start again from a known state. A run that stops
24
24
  without saying what it left behind leaves the developer to discover it.
25
25
 
26
+ ## If one scoped fix can finish this run
27
+
28
+ Do not decide this yourself. This run refused to widen its own scope, and that refusal
29
+ stands. The developer is the one who can widen it.
30
+
31
+ Name the one fix you propose, and say which file or process it touches. Ask the
32
+ developer whether they approve that one fix. If they decline, or the question cannot be
33
+ put to them, stop here and send the report below.
34
+
35
+ If they approve it, make that one fix and nothing else. Then come back into this run:
36
+
37
+ ```text
38
+ npx --yes copilotkit@4.12.0 onboard resume
39
+ ```
40
+
41
+ Write the developer's approval to standard input, in one or two sentences: the fix they
42
+ approved and what it touches. Send no secrets, source code, logs, or command output. The
43
+ command refuses an approval that carries any of those, prints the reason, exits zero, and
44
+ serves nothing. Reword it and send it again.
45
+
46
+ The command prints the run id, the step it puts you back on, and that step's prompt.
47
+ Follow that prompt. This is the same run, so do not run `onboard start` again, and keep
48
+ the run id you already have.
49
+
50
+ If the command refuses for any other reason, it says so and serves nothing. Report what it
51
+ said and stop.
52
+
53
+ ## If no fix is approved
54
+
26
55
  Stop onboarding without making more repository changes.
27
56
 
28
- Send one short report. Run the friction command without another developer question. The
29
- CLI telemetry gate decides whether the report is sent.
57
+ Send one short report. Run the friction command without another developer question. Do not
58
+ ask the developer about telemetry: the command applies the setting they already have.
30
59
 
31
60
  ```text
32
- npx --yes copilotkit@4.10.1 onboard friction --phase stop --category <slug>
61
+ npx --yes copilotkit@4.12.0 onboard friction --phase stop --category <slug>
33
62
  ```
34
63
 
35
64
  Write one or two sentences to standard input: the step you stopped at and what stopped
@@ -153,7 +153,7 @@ here is work the developer did not ask for.
153
153
  Plan the threads drawer itself: add it from the selected drawer page, where this frontend
154
154
  does not already render one. Where this journey's frontend framework ships no threads
155
155
  drawer -- React Native --, plan that the thread is proved by
156
- `npx --yes copilotkit@4.10.1 verify --round-trip`, which needs no browser. Do not plan a
156
+ `npx --yes copilotkit@4.12.0 verify --round-trip`, which needs no browser. Do not plan a
157
157
  step that opens the managed Intelligence dashboard.
158
158
 
159
159
  ## Order the plan into steps
@@ -179,6 +179,12 @@ and one sentence saying what the step changes there and why no other file will d
179
179
  step in the plan. Return `Status: blocked` only when the plan needs a protected path you
180
180
  cannot justify in that sentence.
181
181
 
182
+ Authorization covers changing a protected path, not removing it. Do not plan the deletion
183
+ of a protected path, and do not plan a step that moves or renames one, which removes it
184
+ under its captured name. If a step cannot be written any other way, return
185
+ `Status: blocked` and name the path. The developer approves a plan that changes their
186
+ files, and a plan that deletes one asks for something the audit cannot pass.
187
+
182
188
  Return the protected path list as part of the plan.
183
189
 
184
190
  Keep final validation and proof outside the implementation steps. The developer approves
@@ -3,7 +3,8 @@
3
3
  Implement every step of the approved plan in plan order, and run the full validation list.
4
4
  Do not repeat the full repository inspection.
5
5
 
6
- Do not change a protected path.
6
+ Do not change a protected path. Do not delete, move, or rename one either, whatever the
7
+ plan says: a protected path that is gone fails the audit and no command clears that.
7
8
  Do not change a path that overlaps a protected path. Paths overlap when they are equal or
8
9
  either path is an ancestor directory on a path-segment boundary. `apps/a` overlaps
9
10
  `apps/a/src`, but not `apps/ab`. `app.ts` does not overlap `app.tsx`.
@@ -2,16 +2,41 @@
2
2
 
3
3
  Work only on the packet you were assigned. Inspect the repository without changing it.
4
4
 
5
+ ## Start with what the CLI already knows
6
+
7
+ Run this first, from the target project directory:
8
+
9
+ ```text
10
+ npx --yes copilotkit@4.12.0 onboard inspect --json
11
+ ```
12
+
13
+ It answers the deterministic half of both packets exactly, from the same code
14
+ `copilotkit verify` uses: the project record by presence, and, for each app or runtime
15
+ directory on its own, the env files, which variable carries the Intelligence key and which
16
+ file it came from, whether that directory's own process can load it, the package manager
17
+ its lockfile proves, the port it declares, and the exact installed version of every
18
+ `@copilotkit/*` dependency. It reads only and prints no secret value.
19
+
20
+ Carry those readings into your findings as they came back. Do not work one of them out
21
+ again by reading files. The directory that owns `.env` is the hard case and the CLI holds
22
+ the fixes for it, so a second answer derived here is a guess competing with a proof.
23
+
24
+ An empty `apps` array is an answer, not a failed probe. App discovery keys on a declared
25
+ `@copilotkit/*` dependency, so a project that has not installed CopilotKit reports no apps
26
+ however much else its tree holds. `appDiscovery` says why it is empty: `no-project` for a
27
+ target directory that holds no project yet, and `no-declared-dependency` for a project
28
+ where no directory declares one. Report that reason as the finding. Do not report that
29
+ the inspection found nothing.
30
+
5
31
  ## Project evidence packet
6
32
 
7
33
  Find evidence for:
8
34
 
9
35
  - what the project is for, in the project's own words
10
- - the target app or runtime directory that owns `.env` and the CopilotKit setup
11
36
  - whether the target project directory contains any entries
12
- - any existing agent framework and frontend
13
- - current CopilotKit integration and configuration, including whether
14
- `.copilotkit/project.json` has `projectId`, `projectSlug`, and `clerkOrgId`
37
+ - any existing agent framework and frontend, confirming or contradicting the
38
+ `detection` block the CLI proposed
39
+ - current CopilotKit integration and configuration
15
40
  - authentication boundaries
16
41
  - initial changed and untracked paths, without file contents
17
42
 
@@ -21,25 +46,27 @@ protected-path audit compares against, so nothing later in the run depends on th
21
46
  subagent still existing, and a path that can hold secrets is captured as a digest you
22
47
  never read.
23
48
 
49
+ Take the target app or runtime directory from the CLI packet rather than working it out
50
+ here. `copilotkit verify` resolves it, and two fixes live in that resolution which a
51
+ reading of the files will not reproduce.
52
+
24
53
  ## Environment evidence packet
25
54
 
26
- - names of required credential variables and whether `.env` has a non-empty
27
- `CPK_INTELLIGENCE_API_KEY`
55
+ - names of required credential variables, beyond the Intelligence key the CLI reported
28
56
  - retain the `.env` modification time for a later comparison without returning it
29
- - package manager and lockfile
30
57
  - required toolchains and their installed versions
31
- - declared ports and whether each port is available
58
+ - whether each port the CLI reported as declared is free
32
59
  - whether the runtime constructor uses a `runner` option, an `intelligence` option, or
33
60
  neither can be proved from project files
34
- - CopilotKit package versions and package compatibility risks
61
+ - package compatibility risks, and whether any `@copilotkit/*` version the CLI reported is
62
+ below 1.70.0
35
63
 
36
64
  Key every environment finding by its app or runtime directory. Do not combine findings
37
- from different directories.
65
+ from different directories. The CLI packet keys its own readings the same way.
38
66
 
39
- For the CopilotKit versions, report the exact installed version of every `@copilotkit/*`
40
- dependency, read from the lockfile rather than a manifest range, and state whether any of
41
- them is below 1.70.0. The conversion decides its upgrade from exactly that, and a caret
42
- range does not answer it.
67
+ The CLI reports the exact installed version of every `@copilotkit/*` dependency, read from
68
+ the installed tree rather than from a manifest range. The conversion decides its upgrade
69
+ from exactly that, and a caret range does not answer it.
43
70
 
44
71
  A project states what it is for in its `README.md`, in its package description, or in
45
72
  the prompt of an agent it already has. Quote that statement rather than rewriting it. An
@@ -59,5 +86,5 @@ Return one row for each assigned item with its status, evidence path, and a shor
59
86
  Use only `proved`, `absent`, or `unproved` for the status. State each absent or unproved item.
60
87
  Do not read, print, or return secret values. For `.env` and `.copilotkit/project.json`
61
88
  checks, return only paths, presence checks, and missing field names. Do not read a file
62
- outside the project directory. Do not run or return another onboarding command. Stop after
63
- returning the findings to the main coding agent.
89
+ outside the project directory. Do not run or return an onboarding command other than
90
+ `onboard inspect`. Stop after returning the findings to the main coding agent.
@@ -19,7 +19,7 @@ Prove the live runtime in this order:
19
19
  4. Confirm from project files that the runtime constructor passes a `runner` option rather
20
20
  than an `intelligence` option. A package, import, project file, or key is not use proof.
21
21
  5. Run
22
- `npx --yes copilotkit@4.10.1 verify --expect-runtime oss --round-trip --agent <expected-agent-id> --json`,
22
+ `npx --yes copilotkit@4.12.0 verify --expect-runtime oss --round-trip --agent <expected-agent-id> --json`,
23
23
  with the runtime URL or auth header options that this project needs. Require exit zero
24
24
  and the JSON `ok` field to be `true`.
25
25
  6. Drive one real request through the existing frontend, CopilotKit runtime, and expected
@@ -135,7 +135,7 @@ IPv6 only, so an IPv4 literal fails against the correct port.
135
135
  ## Step 4 -- Check the wiring
136
136
 
137
137
  With both running, check the wiring in one command before you open a browser:
138
- `npx --yes copilotkit@4.10.1 verify --json`. It reads the port from this project, so a
138
+ `npx --yes copilotkit@4.12.0 verify --json`. It reads the port from this project, so a
139
139
  non-default port needs no flag. The payload reports `runtimeUrl` and `runtimeUrlSource`. A
140
140
  `runtimeUrlSource` of `default` means nothing in the project named a port, so pass
141
141
  `--runtime-url` with the URL from step 1 in that case. Read the individual checks rather than
@@ -149,10 +149,11 @@ used the Intelligence credential. `api_key_authenticates` proves only that the k
149
149
  `api_key_loadable_by_app` fails when the key is in a file the application's own process
150
150
  will not read. `verify` searches upward for the credential and a framework's env loader
151
151
  does not, so a key at the repository root is invisible to an app in a subdirectory. The
152
- check names the file to write instead. Write the key there, or run
153
- `npx --yes copilotkit@4.10.1 project select` from the app directory. Do not link,
154
- copy, or symlink the file to work around it, and do not treat the credential as missing:
155
- the check above already reported that it exists.
152
+ check names the file to write instead, and it names the exact command to re-run with this
153
+ project already chosen. Write the key there, or run the command the check names, from the
154
+ app directory. Do not run a bare `project select`: with no project named it needs a
155
+ terminal you do not have. Do not link, copy, or symlink the file to work around it, and do
156
+ not treat the credential as missing: the check above already reported that it exists.
156
157
 
157
158
  `intelligence_thread_routes` fails when a licensed runtime serves no thread routes. A missing
158
159
  `identifyUser` is the usual cause: it gates the whole web surface. Return the check for
@@ -168,7 +169,7 @@ named no port the CLI can read: keep step 2's URL, and rewrite its host as `loca
168
169
  before you use it.
169
170
 
170
171
  Then run the command once more with the URL you are about to open:
171
- `npx --yes copilotkit@4.10.1 verify --frontend-url <that url> --json`. The
172
+ `npx --yes copilotkit@4.12.0 verify --frontend-url <that url> --json`. The
172
173
  `frontend_assets_served` check asks that server for its page and for one of the page's own
173
174
  assets, on that exact host. A `fail` there means the dev server refuses its own static
174
175
  assets on the host you were about to use, and the check names the URL to use instead. This
@@ -176,7 +177,7 @@ is the cheapest step that can save the most expensive one, so run it before the
176
177
 
177
178
  ## Step 5 -- Prove that the agent runs
178
179
 
179
- Run `npx --yes copilotkit@4.10.1 verify --round-trip --json`. It sends one request through
180
+ Run `npx --yes copilotkit@4.12.0 verify --round-trip --json`. It sends one request through
180
181
  the runtime and reads the answer back from the thread, so it separates an agent that is
181
182
  configured from an agent that works. Use `--agent <id>` when the runtime declares more
182
183
  than one. If it reports `user-not-identified`, this project's `identifyUser` reads a
@@ -189,7 +190,7 @@ Where this run settled a Learning Container, add the flag to the call above rath
189
190
  running a second round trip:
190
191
 
191
192
  ```text
192
- npx --yes copilotkit@4.10.1 verify --round-trip --expect-learning-container <container id> --json
193
+ npx --yes copilotkit@4.12.0 verify --round-trip --expect-learning-container <container id> --json
193
194
  ```
194
195
 
195
196
  The check reads the thread that this run created, so a second round trip proves a second
@@ -217,6 +218,22 @@ callback rather than from an assigned thread. Never report either one as proof.
217
218
 
218
219
  Where this run skipped the Learning step, leave the flag off.
219
220
 
221
+ Where the runtime answers with a 401 from the model provider, check the processes before
222
+ you change anything. A process reads its env file once, at launch, so one started before
223
+ the credential was written holds an empty key while the file beside it carries the real
224
+ one. Run this from the target app directory:
225
+
226
+ ```text
227
+ npx --yes copilotkit@4.12.0 onboard env-staleness
228
+ ```
229
+
230
+ A `stale` line names the env file and how long after launch it was written. Report that,
231
+ with the process and the file it named, and say the process has to be started again before
232
+ the 401 means anything. Do not restart it yourself and do not stop it: the reading names a
233
+ process and never its owner, and one project's dev script often serves the agent and the
234
+ frontend together. Editing a file to answer a 401 that a restart clears changes the project
235
+ for a fault it does not have.
236
+
220
237
  ### Step 5a -- Prove that the page's data reaches the model
221
238
 
222
239
  `verify --round-trip` sends `context: []` and asks a question that needs no context. It
@@ -285,7 +302,7 @@ For a recorded `both-oss` starting state, this step has no component to render.
285
302
  same request the baseline recorded, require the same kind of user-visible result the
286
303
  baseline produced, and require that the thread for that request is listed in the drawer.
287
304
  Where this journey's frontend framework ships no threads drawer -- React Native --, prove
288
- that thread with `npx --yes copilotkit@4.10.1 verify --round-trip`, which reads the
305
+ that thread with `npx --yes copilotkit@4.12.0 verify --round-trip`, which reads the
289
306
  answer back off the thread and needs no browser. Record which of the two you proved.
290
307
 
291
308
  Use the surface control the main coding agent recorded for your environment. It either had
@@ -313,7 +330,7 @@ request never exercises. Drive it with the browser control step 6 named.
313
330
  the page to finish loading. Do not retype the host, and do not substitute a URL a tool
314
331
  offers you by default. Where the page loads but its styling is missing or the chat
315
332
  control is dead, run
316
- `npx --yes copilotkit@4.10.1 verify --frontend-url <the url you opened> --json`
333
+ `npx --yes copilotkit@4.12.0 verify --frontend-url <the url you opened> --json`
317
334
  before you diagnose anything else. A dev server can serve its page and refuse every
318
335
  static chunk behind it, and on screen that is indistinguishable from a broken
319
336
  integration. The `frontend_assets_served` check tells the two apart.
@@ -337,8 +354,9 @@ request never exercises. Drive it with the browser control step 6 named.
337
354
  9. Record one line for the finished turn: the time, the page URL, the element you read
338
355
  the answer from, and what that element showed.
339
356
 
340
- Report exactly one of `performed`, `skipped-no-browser-tool`, or `failed` for a web
341
- frontend.
357
+ Report exactly one of `performed`, `skipped-no-browser-tool`, `skipped-cloned-starter`, or
358
+ `failed` for a web frontend. Report `skipped-cloned-starter` when this prompt told you to
359
+ open no browser because the run cloned a starter.
342
360
 
343
361
  ### Step 6b -- React Native
344
362
 
@@ -363,7 +381,8 @@ An Android emulator reaches a runtime on the host machine at `10.0.2.2` rather t
363
381
  `localhost`. A request that fails against the runtime with nothing in the runtime's own
364
382
  log is that, rather than a broken runtime.
365
383
 
366
- Report exactly one of `performed`, `skipped-no-device`, or `failed` for React Native.
384
+ Report exactly one of `performed`, `skipped-no-device`, `skipped-cloned-starter`, or
385
+ `failed` for React Native.
367
386
 
368
387
  ## Step 7 -- Check the answer against the project's data
369
388
 
@@ -412,7 +431,7 @@ it, rather than reading the compatibility field as a pass.
412
431
  For every other starting state, record Step 8 as not applicable.
413
432
 
414
433
  The application edit ban ends only after Step 8 passes or is recorded as not applicable.
415
- Step 9 can write only the tool files named by its guide.
434
+ Step 9 can write only the tool files named by its guide or by this step.
416
435
 
417
436
  ## Step 9 -- Set up the continued-development tools
418
437
 
@@ -423,12 +442,27 @@ Tell the developer what the skills install writes into this project before you r
423
442
  `.agents/skills` directory holding one folder per CopilotKit skill, linked into
424
443
  `.claude/skills`. Both sit in the working tree, so the install shows up in `git status`
425
444
  and can land in a commit. You cannot know whether this project keeps those directories in
426
- version control, so name them before you write them rather than after.
445
+ version control, so name them before you write them rather than after. Say the same
446
+ thing about the MCP registration below where it writes `.mcp.json`: that file lands in the
447
+ working tree beside them, for the same reason and with the same consequence.
427
448
 
428
449
  Use it to install the project-scoped CopilotKit Skills.
429
- Use it to configure the CopilotKit documentation MCP server for the current coding agent.
430
- That registration goes in the coding agent's own configuration for this project, not in
431
- the working tree.
450
+ Use it to configure the CopilotKit documentation MCP server for the coding-agent slug this
451
+ run reported to `onboard identify`.
452
+
453
+ Register it in this project wherever that agent reads a project-scoped file. For
454
+ `claude-code` that is `claude mcp add --scope project`, which writes `.mcp.json` at the
455
+ project root. Without that flag the command writes the agent's own configuration under the
456
+ developer's home directory, outside this project, so pass it even where the command line
457
+ you were given leaves it out. For `github-copilot` the project-scoped file is
458
+ `.vscode/mcp.json`, and for `cursor` it is the project `mcp.json`.
459
+
460
+ Where the agent reads no project-scoped file at all, do not run the registration. `codex`
461
+ and `windsurf` write only under the home directory, and the desktop and web clients
462
+ register through a settings screen this run cannot reach. Print the exact command or
463
+ setting the guide gives for that agent, and tell the developer it is theirs to run. Record
464
+ that as handed over rather than as failed: nothing went wrong, and this run is not allowed
465
+ to edit configuration outside the project.
432
466
 
433
467
  Check whether each install succeeded and record what you found. Record the command result
434
468
  for each attempt. Report the Skills result and the MCP result separately from the proof
@@ -30,13 +30,13 @@ Before you show the best-effort plan, require this complete packet:
30
30
  - Give the ordered proof rules.
31
31
 
32
32
  After the developer approves the best-effort plan, run
33
- `npx --yes copilotkit@4.10.1 onboard read fallback/best-effort`.
33
+ `npx --yes copilotkit@4.12.0 onboard read fallback/best-effort`.
34
34
 
35
- Send one short report. Run the friction command without another developer question. The
36
- CLI telemetry gate decides whether the report is sent.
35
+ Send one short report. Run the friction command without another developer question. Do not
36
+ ask the developer about telemetry: the command applies the setting they already have.
37
37
 
38
38
  ```text
39
- npx --yes copilotkit@4.10.1 onboard friction --phase stop --category <slug>
39
+ npx --yes copilotkit@4.12.0 onboard friction --phase stop --category <slug>
40
40
  ```
41
41
 
42
42
  Write one or two sentences to standard input: the step you stopped at and what stopped it.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "copilotkit",
3
- "version": "4.10.1",
3
+ "version": "4.12.0",
4
4
  "type": "module",
5
5
  "repository": {
6
6
  "type": "git",
@@ -10,7 +10,8 @@
10
10
  "bin": {
11
11
  "copilotkit": "./index.js"
12
12
  },
13
- "dependencies": {
13
+ "optionalDependencies": {
14
14
  "@microsoft/teams.cli": "3.0.3"
15
- }
15
+ },
16
+ "license": "SEE LICENSE IN LICENSE"
16
17
  }
@@ -14698,7 +14698,7 @@ import * as path4 from "node:path";
14698
14698
 
14699
14699
  // apps/cli/src/config.ts
14700
14700
  function getTemplateRef() {
14701
- return true ? "7e6964fc11092b685bbea62bc331d5d177b738c1" : "main";
14701
+ return true ? "0048ba241fdf14a9036cdad11a4f31aa021a9c8d" : "main";
14702
14702
  }
14703
14703
 
14704
14704
  // apps/cli/src/services/agentcore-config.ts