copilotkit 4.21.0 → 4.22.0

package/onboarding/prompts/subagent/prove-round-trip.md

@@ -6,7 +6,7 @@ policy the main coding agent gives you before you start.
 During Steps 1 through 8, do not edit source files, configuration files, dependencies, or
 tracked files.
 You can make only operational repairs to project-owned processes, ports, and request options,
-and the credential write that Step 4 names for `api_key_loadable_by_app`.
+and the credential command that `verify:api_key_loadable_by_app` names.
 Do not write a path that overlaps a protected path. If a required proof or tool path
 overlaps one, return `Status: blocked` before writing it.
 
@@ -32,12 +32,11 @@ convincing. Step 6 has a web form and a React Native form: run the one that matc
 journey's frontend, and run only that one.
 
 A run that cloned a starter is the one exception. When the main coding agent tells you
-that this run cloned a starter, run Steps 1 through 5 up to and including the
-`verify --round-trip` command, then go to Step 10. Skip Steps 5a through 9, open no browser
+that this run cloned a starter, run Step 1 and the proof checks, then go to Step 10. Skip Steps 5a through 9, open no browser
 or device, and report `skipped-cloned-starter` as the surface-check outcome.
 
-Where this is a second attempt after a repair, run every step from Step 2 through Step 7
-again, or through the Step 5 `verify --round-trip` command for a cloned-starter run. The repair changed tracked files and restarted processes, so the wiring, the agent
+Where this is a second attempt after a repair, run every step from the proof checks through
+Step 7 again, or only the proof checks for a cloned-starter run. The repair changed tracked files and restarted processes, so the wiring, the agent
 identity, and both preconditions are stale. Step 1 is the exception, and it is carried
 rather than derived a second time. Compare the Step 5a and Step 5b results against the
 failed attempt's before you drive the surface. A repair that leaves the failed precondition
@@ -74,246 +73,89 @@ step. Use its request words, expected agent id, entity list, and runtime URL unc
 do not write a new request. A second attempt that asks a different question proves nothing
 about the failure it was spawned to clear.
 
-## Step 2 -- Start the agent and the frontend
-
-Read the port the developer's agent already serves from this project's own configuration.
-Do not assume a default, and do not start a second copy of an agent this project is
-already running. Before you bind any new server, check that the port is free and pick
-another one if it is not. Record every port you used.
-
-The table names what each frontend's own scaffolder writes, for recognizing a port in a
-started process's output. The project's configuration wins over the table.
-
-| Frontend     | Dev server the scaffolder writes |
-| ------------ | -------------------------------- |
-| Next.js      | `next dev`, port 3000            |
-| React SPA    | Vite, port 5173                  |
-| Vue 3        | Vite, port 5173                  |
-| Angular      | `ng serve`, port 4200            |
-| React Native | Metro, port 8081                 |
-
-Where this project's runtime runs as a process of its own, the frontend documentation
-puts it on port 8200. Use the runtime URL from step 1 rather than that number.
-
-Read the project's scripts before you start anything. A scaffolded starter serves both the
-agent and the frontend from one `dev` script, which runs them under
-`concurrently --kill-others`. One command starts both, and stopping either one stops the
-other. A second start against a project already running that script collides with a server
-that is up.
-
-`next dev` locks its build directory, not its port. Next 16 writes `.next/dev/lock`. A
-second `next dev` in the same app exits with `Unable to acquire lock at ..., is another
-instance of next dev running?`. A free port does not help.
-
-Before you start a Next.js frontend, look for a `next dev` process that runs from this app.
-If one runs, reuse that server. Read its port from its command line or its listener, and
-prove against that port. If a start still fails with that message, name the process that
-holds the lock. Give its PID and working directory. Do not stop it unless it belongs to
-this project.
-
-If your harness runs commands in a sandbox, a sandboxed command cannot listen on a port or
-connect to localhost. Before the first server start, request escalation with a prefix rule
-for the project's own dev script. Before the first request to a local server, request
-escalation with a prefix rule for `curl`. If a local request still fails after 0 ms
-(`Failed to connect ... after 0 ms`) while the port shows a listener, the sandbox blocked
-it. Run it again with escalation, and do not record a failed predicate or step.
-
-Start each server in the background with the project's own script. Then wait for it to
-answer rather than for a fixed number of seconds:
-
-```bash
-curl -fs -o /dev/null --retry 90 --retry-delay 1 --retry-max-time 90 --retry-all-errors "<url>"
-```
-
-A zero exit means the server answered. Any other exit means that it did not answer in 90
-seconds. A server that never answered has written the reason to its own output, and
-reading that output is faster than starting it again.
-
-When the server that serves the runtime answers, record the URL it serves on. Read the port
-from that server's own output or its listener, not from the plan. A dev server whose port
-is taken moves to the next free one without asking. Where the runtime runs as a process of
-its own, this is the runtime's port, not the frontend's.
-
-```text
-npx --prefer-offline --yes copilotkit@4.21.0 onboard runtime-url --url <runtime-url>
-```
-
-`<runtime-url>` is the Step 1 runtime URL with its port replaced by the port that server
-bound. Keep its host and its mount path unchanged.
-
-The command writes `runtimeUrl` into `.copilotkit/project.json` and changes nothing else. It
-mints no key and does not touch `.env`. Step 4 reads that record, so `verify` probes the
-server you started. Run the command again after any restart that binds another port.
-
-That coupling also turns an ordinary restart into a false failure. Where you stop a server
-to pick up an installed dependency, start both again and wait for both to answer before you
-read the round trip. A check run against a frontend whose agent was stopped with it reports
-a wiring fault this run does not have.
-
-Leave the agent and frontend servers running after proof. Record each process ID and a
-safe command that stops that process. Record whether that command stops both. Record the
-commands that start both servers again.
-
-Record the frontend URL the server you started reports, and treat it as provisional. Step 4
-replaces it with the URL the CLI resolves. Do not compose one of your own from a port you
-read here.
-
-## Step 3 -- Identify the process that answered
-
-Before you trust the agent, confirm that the process answering is the one in this
-repository. `verify` reports which agents the runtime declares and has nothing to compare
-them against, and `--round-trip` proves an agent answers under the declared id without
-proving which deployment did, so this comparison is yours. A health endpoint that returns
-success proves only that something listens on
-that port. An agent from earlier work often still holds it, and a stale process answers
-as though it were the new one. Ask the running agent which graph or agent id it serves
-and compare that with the id declared in this project.
-
-If they do not match, find out whose process it is before you signal anything.
-`lsof -ti :<port> -sTCP:LISTEN` gives the process id, and `lsof -a -p <pid> -d cwd` gives
-the directory it runs in. Stop it only when that directory is inside this project, and
-stop its children before the parent so nothing survives by reparenting. A holder outside
-this project belongs to other work: leave it running, report it, and bind to another port.
-Never stop a process because its command line matches a name. One `pkill` pattern reaches
-every project on the machine and takes down work that has nothing to do with this run.
-Never continue against a process you cannot identify, and never report a round trip proven
-by one.
-
-Address a local agent by host name rather than by an IP literal. Some local agents bind
-IPv6 only, so an IPv4 literal fails against the correct port.
-
-## Step 4 -- Check the wiring
-
-With both running, check the wiring in one command before you open a browser:
-`npx --prefer-offline --yes copilotkit@4.21.0 verify --json`. It reads the port from this project, so a
-non-default port needs no flag. The payload reports `runtimeUrl` and `runtimeUrlSource`. A
-`runtimeUrlSource` of `default` means nothing in the project named a port, so the Step 2
-record is missing. Run the Step 2 `onboard runtime-url` command, then run `verify` again. Read the individual checks rather than
-the summary alone: a check reported `undetermined` did not run, and that is not a pass.
-Repair a failed check only within the limits above. Otherwise, return the check and its
-evidence before the browser.
-
-Treat `intelligence_consumed` as the check that matters most here. It proves that the runtime
-used the Intelligence credential. `api_key_authenticates` proves only that the key is valid.
-
-`api_key_loadable_by_app` fails when the key is in a file the application's own process
-will not read. `verify` searches upward for the credential and a framework's env loader
-does not, so a key at the repository root is invisible to an app in a subdirectory. The
-check names the file to write instead, and it names the exact command to re-run with this
-project already chosen. Write the key there, or run the command the check names, from the
-app directory. Do not run a bare `project select`: with no project named it needs a
-terminal you do not have. Do not link, copy, or symlink the file to work around it, and do
-not treat the credential as missing: the check above already reported that it exists.
-
-`intelligence_thread_routes` fails when a licensed runtime serves no thread routes. A missing
-`identifyUser` is the usual cause: it gates the whole web surface. Return the check for
-implementation to pass `identifyUser` where the runtime is constructed. Do not edit it.
-A handler mounted `mode: "single-route"` is not a cause and must never be removed to satisfy
-this check: that mount serves the thread routes inside its envelope. If the check is
-`undetermined`, the runtime cannot report the state, and the check names the upgrade. Record
-that and continue.
-
-`single_route_core_supports_intelligence` and `frontend_runtime_url_resolvable` read the
-installed `@copilotkit/core` and the frontend's `runtimeUrl`. Each names the upgrade or the
-URL that fixes it. Return the check for implementation. Do not edit it.
-
-Take the frontend URL from the payload's `frontendUrl`. It replaces whatever step 2
-recorded, and every later step uses it unchanged. Where the field is absent, the project
-named no port the CLI can read: keep step 2's URL, and rewrite its host as `localhost`
-before you use it.
-
-Then run the command once more with the URL you are about to open:
-`npx --prefer-offline --yes copilotkit@4.21.0 verify --frontend-url <that url> --json`. The
-`frontend_assets_served` check asks that server for its page and for one of the page's own
-assets, on that exact host. A `fail` there means the dev server refuses its own static
-assets on the host you were about to use, and the check names the URL to use instead. This
-is the cheapest step that can save the most expensive one, so run it before the browser.
-
-## Step 5 -- Prove that the agent runs
-
-Run `npx --prefer-offline --yes copilotkit@4.21.0 verify --round-trip --json`. It sends one request through
-the runtime and reads the answer back from the thread, so it separates an agent that is
-configured from an agent that works. Use `--agent <id>` when the runtime declares more
-than one. If it reports `user-not-identified`, this project's `identifyUser` reads a
-session the CLI does not carry: pass what it reads with `--header "Name: value"` and run
-it again, because an auth-gated app refusing an unauthenticated caller is that app
-working. Do not continue until the `roundTrip` entry passes, and never report a round trip
-proven without it.
-
-The command exits non-zero for any check that is not `pass`, including each `extraChecks`
-entry, so route on each entry's own `status` rather than on the exit status. Where the
-frontend's files call a context hook, one entry has the `id` `page_context_reaches_agent`:
-
-- `pass` proves that the agent's model sees context the page sends.
-- `fail` is a defect: the agent answered the plain request and recorded nothing for the
-  request that carried context. Return it with its evidence as a failed proof step.
-- `undetermined` means the context round trip did not complete, or the agent answered
-  without the value. An agent scoped to its own task declines to repeat an arbitrary value
-  even when the context reaches its model, so this is not a defect. Record it, and prove
-  the path in Step 5a.
-
-Where this run settled a Learning Container, add the flag to the call above rather than
-running a second round trip:
-
-```text
-npx --prefer-offline --yes copilotkit@4.21.0 verify --round-trip --expect-learning-container <container id> --json
-```
-
-The check reads the thread that this run created, so a second round trip proves a second
-thread and leaves the first unexamined. Add `--agent <id>` here too when the runtime
-declares more than one.
-
-It reads the thread back from the platform, so it answers for every runtime mount,
-including a single-route one. Read the `extraChecks` entry whose `id` is
-`learning_container_assigned`, and route on that entry's own `status` rather than on the
-exit status: the command exits non-zero for any check that is not `pass`, and
-`undetermined` is what a runtime the CLI cannot read reports.
-
-- `pass` proves the assignment. The thread came back carrying the container this run
-  settled.
-- `fail` is a defect. Either the thread carries no container, which means the selector
-  returned nothing, or it carries a different one. A thread cannot move between containers
-  after its first assignment, so start a new thread rather than repairing that one.
-- `undetermined` proves nothing either way. Record it and continue. An auth-gated
-  `identifyUser` produces it on an app that works, and so does a runtime the CLI cannot
-  read.
-
-`features.self_learning` and `/info` are not evidence. The first is a plan entitlement and
-is already true before any wiring. The second reports Learning from the presence of a
-callback rather than from an assigned thread. Never report either one as proof.
-
-Where this run skipped the Learning step, leave the flag off.
-
-Where the runtime answers with a 401 from the model provider, check the processes before
-you change anything. A process reads its env file once, at launch, so one started before
-the credential was written holds an empty key while the file beside it carries the real
-one. Run this from the target app directory:
-
-```text
-npx --prefer-offline --yes copilotkit@4.21.0 onboard env-staleness
-```
-
-A `stale` line names the env file and how long after launch it was written. Report that,
-with the process and the file it named, and say the process has to be started again before
-the 401 means anything. Do not restart it yourself and do not stop it: the reading names a
-process and never its owner, and one project's dev script often serves the agent and the
-frontend together. Editing a file to answer a 401 that a restart clears changes the project
-for a fault it does not have.
+## Steps 2 to 5 -- Run the proof checks
 
-Where the runtime answers with a 404 from the model provider, check the base URLs the
-processes inherited before you change anything. A coding agent's shell passes its own
-environment on to every process it starts, so a provider base URL exported for the agent
-reaches the dev servers. Run this from the target app directory:
+Run this from the target app directory:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.21.0 onboard inspect --json
+npx --prefer-offline --yes copilotkit@4.22.0 onboard proof-check --json
 ```
 
-Read `providerEndpoints` for the app directory. An entry with a `null` `source` came from
-the process environment rather than from a project file. A `warning` names why that value
-fails. Report the variable, where it came from, and the warning, and say that the server
-has to start from an environment without that value before the 404 means anything. Do not
-edit a project file to answer it: the value lives in the shell, not in the project.
+It starts each app's `dev` script unless a server from that app already listens, and
+waits for the runtime to answer. It checks that the process on the runtime port runs inside
+this project, runs the wiring checks, the frontend asset check, and the round trip, and
+reads stale env files and inherited provider base URLs. Add `--agent <id>` when the runtime
+declares more than one agent.
+
+It starts only the apps that depend on CopilotKit. If the agent runs somewhere else, for
+example a Python agent or a root script that starts both halves, pass the start command
+from your Step 1 record with `--server <directory>=<command>`. A relative `<directory>` is
+read from the directory you run the command in, so a sibling agent folder is `../agent`. It
+does not start an app inside that directory a second time. If your harness runs commands in a sandbox, request
+escalation for this command first: it starts servers and connects to localhost.
+
+When `status` is `passed`, record `servers`, with their process IDs and stop commands, for
+the handoff, and take the URL to open from `frontendUrl`. If `frontendUrl` is absent, the
+project named no port the CLI can read: take the URL from the frontend server's log, and
+use `localhost` as its host.
+
+A pass on `runtime-process-in-project` proves only that the process runs inside this
+project. Ask the running agent which graph or agent ID it serves, and compare that with the
+expected agent ID from Step 1. If they differ, an older build still answers on the port.
+Report it, and stop it only under the rule below. The servers keep running after
+the proof. Then go to Step 5a.
+
+Otherwise sort `firstFailure`, and run the command again after each repair:
+
+- `runtime-answers`: nothing answered, or the project records no runtime URL. Read the
+  server log it names. A dev server whose port is taken moves to the next free one without
+  asking, and a starter's project records no URL until its server binds a port. Read the
+  port from the log, not from the plan, and record it:
+
+  ```text
+  npx --prefer-offline --yes copilotkit@4.22.0 onboard runtime-url --url <runtime-url>
+  ```
+
+  `<runtime-url>` is the project's runtime URL, or the plan's, with its port replaced by the
+  port the server bound. Keep its host and its mount path unchanged. The command can write
+  `.copilotkit/project.json` even when that path is protected. It moves the protected-path
+  baseline with its own write. It mints no key and does not touch `.env`. Then run the
+  checks again.
+- `runtime-process-in-project`: another project's process holds the runtime port. Leave it
+  running, and report it.
+- `verify:api_key_loadable_by_app`: the key is in a file the app does not read. Run the
+  command the check names, from the app directory. Do not copy or link the key file.
+- `verify:intelligence_thread_routes`: usually a missing `identifyUser` where the runtime is
+  constructed. Return it for implementation. Never remove a `mode: "single-route"` mount
+  to satisfy it.
+- `round-trip:agent_answers` naming `user-not-identified`: this project's `identifyUser` reads a
+  session the CLI does not carry. Run again with `--header "Name: value"` for what it reads.
+- `round-trip:page_context_reaches_agent` at `fail`: the agent answered the plain request
+  and recorded nothing for the request that carried context. Return it with its evidence as
+  a failed proof step. At `undetermined` and marked `advisory`, the agent answered without
+  the value, and the checks still pass: an agent scoped to its own task declines to repeat
+  an arbitrary value, so prove the path in Step 5a. At `undetermined` without `advisory`,
+  the context run did not complete, and the checks fail on it. Run them again once. If it
+  still does not complete, prove the path in Step 5a, and report the check with its detail.
+- `round-trip:learning_container_assigned` at `fail`: the thread carries no container or
+  another one. A thread cannot move, so start a new thread rather than repairing that one.
+  `features.self_learning` and `/info` are not evidence of an assignment.
+- `env-files-current`: the process it names started before its env file was written, and
+  has to start again before a 401 means anything. Report it. Do not restart or stop it.
+- `provider-endpoints`: a provider base URL came from the shell, and the round trip reports
+  a 404 from the model provider. Report it. The server has to start from an environment
+  without it. Do not edit a project file.
+- Any other `verify:` check: repair it only within the limits above, or return it with its
+  evidence before the browser.
+
+Never report a round trip proved unless `round-trip:agent_answers` passed.
+
+The checks leave every process they did not start running. If a repair needs a process
+stopped, stop a process only when its directory is inside this project, and stop its children
+before the parent. Never stop a process because its command line matches a name: one
+`pkill` pattern reaches every project on the machine. If a local request in Steps 5a and
+5b fails after 0 ms while the port listens, the sandbox blocked it. Request escalation
+with a prefix rule for `curl`, run it again, and do not record a failed predicate.
 
 ### Step 5a -- Prove that the page's data reaches the model
 
@@ -396,7 +238,7 @@ For a recorded `both-oss` starting state, this step has no component to render.
 same request the baseline recorded, require the same kind of user-visible result the
 baseline produced, and require that the thread for that request is listed in the drawer.
 Where this journey's frontend framework ships no threads drawer -- React Native --, prove
-that thread with `npx --prefer-offline --yes copilotkit@4.21.0 verify --round-trip`, which reads the
+that thread with `npx --prefer-offline --yes copilotkit@4.22.0 verify --round-trip`, which reads the
 answer back off the thread and needs no browser. Record which of the two you proved.
 
 Use the surface control the main coding agent recorded for your environment. That finding
@@ -424,17 +266,17 @@ limit can be ten minutes. You cannot interrupt a call while it runs, so the limi
 what you do after one. If a browser call took longer than 60 seconds to return, the browser
 control is unresponsive. Do not call the browser again in this attempt. A second call to a
 hung tool waits as long as the first one did. Run
-`npx --prefer-offline --yes copilotkit@4.21.0 verify --frontend-url <the url step 4 resolved> --json` once,
+`npx --prefer-offline --yes copilotkit@4.22.0 verify --frontend-url <the frontendUrl the proof checks resolved> --json` once,
 and record the `frontend_assets_served` result. Report the outcome `failed` with the cause
 `browser-control-unresponsive`. The application is not at fault on this evidence: every
 step before the browser proved the runtime without one, and no repair to the project can
 reach the tool.
 
-1. Open the frontend URL step 4 resolved, exactly as that step recorded it, and wait for
+1. Open the `frontendUrl` the proof checks resolved, exactly as they reported it, and wait for
    the page to finish loading. Do not retype the host, and do not substitute a URL a tool
    offers you by default. Where the page loads but its styling is missing or the chat
    control is dead, run
-   `npx --prefer-offline --yes copilotkit@4.21.0 verify --frontend-url <the url you opened> --json`
+   `npx --prefer-offline --yes copilotkit@4.22.0 verify --frontend-url <the url you opened> --json`
    before you diagnose anything else. A dev server can serve its page and refuse every
    static chunk behind it, and on screen that is indistinguishable from a broken
    integration. The `frontend_assets_served` check tells the two apart.

package/onboarding/prompts/unsupported/no-validated-path.md

@@ -30,13 +30,13 @@ Before you show the best-effort plan, require this complete packet:
 - Give the ordered proof rules.
 
 After the developer approves the best-effort plan, run
-`npx --prefer-offline --yes copilotkit@4.21.0 onboard read fallback/best-effort`.
+`npx --prefer-offline --yes copilotkit@4.22.0 onboard read fallback/best-effort`.
 
 Send one short report. The friction command follows the telemetry setting the developer
 already chose, so it needs no separate question.
 
 ```text
-npx --prefer-offline --yes copilotkit@4.21.0 onboard friction --phase stop --category <slug> --message "<sentences>"
+npx --prefer-offline --yes copilotkit@4.22.0 onboard friction --phase stop --category <slug> --message "<sentences>"
 ```
 
 `--message` takes one or two sentences: the step you stopped at and what stopped it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "copilotkit",
-  "version": "4.21.0",
+  "version": "4.22.0",
   "type": "module",
   "engines": {
     "node": ">=20.9.0"

package/release/release-tool.js

@@ -14823,7 +14823,7 @@ var FLAG_DEFINITIONS = defineFlags({
 
 // apps/cli/src/config.ts
 function getTemplateRef() {
-  return true ? "3dc45f8bdca6665af9b4cc5cecfbcb8ab057e426" : "main";
+  return true ? "4b51d880eab2617e3196285ddcf0e4ff7b34a237" : "main";
 }
 
 // apps/cli/src/services/agentcore-config.ts