copilotkit 4.28.0 → 4.30.0

package/onboarding/prompts/subagent/implement-and-validate.md

@@ -89,6 +89,19 @@ approved paths that do not overwrite such a file, unless the plan lists it under
 running the scaffolder. Ask the main coding agent to revise credential setup when a
 required variable is missing. Do not provision another key to repair a scaffold overwrite.
 
+## When a command is refused
+
+If you are a subagent and your harness refuses a command, return at once. Name the
+command, the directory you ran it from, and the refusal, and run nothing else. Do not wait
+for an approval: nobody sees it. The main coding agent runs the command itself and passes
+the result on. The one wait allowed is a harness escalation request that this brief tells
+you to make for a command. Make that request and wait for its answer.
+
+If your handoff holds a command's result, use it and do not run that command again.
+
+If you are the main coding agent and follow this brief yourself, this section is not for
+you. Do not return: handle a refused command as the run's other prompts say.
+
 ## What the existing agent's behavior is
 
 The existing agent's behavior is four things: its system prompt and instructions, its
@@ -136,7 +149,7 @@ Intelligence: declare each exact version in its app's manifest, then install wit
 project's package manager, under the install rule above. Then check the installed tree:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.28.0 onboard upgrade-plan --check --json
+npx --prefer-offline --yes copilotkit@4.30.0 onboard upgrade-plan --check --json
 ```
 
 `single` means every direct dependency resolved to one version. `duplicates` names each
@@ -151,7 +164,7 @@ If the check finds duplicates or the baseline regresses, put the manifests and l
 back, leave Intelligence unwired, and report what failed:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.28.0 onboard upgrade-plan --revert --json
+npx --prefer-offline --yes copilotkit@4.30.0 onboard upgrade-plan --revert --json
 ```
 
 Then end your turn. Never add an `overrides`, `resolutions`, or `pnpm.overrides` block to
@@ -183,11 +196,16 @@ project does not hold, and the rendered result looks the same either way.
 Run the full validation list. Record changed files, command results, and errors. Do not
 claim that the real user journey works in this phase.
 
+Your validation stops at `verify`. The proof step runs the round trip and records the
+proof, once. Do not run `verify --round-trip`, `onboard proof-check`, or `onboard proof`.
+Where the validation list names the round trip, leave it to the proof step and say so in
+the Validation section.
+
 Where the plan names a Learning Container id, check that the container exists first. Run
 this from the target app directory, before you write any selector:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.28.0 learning containers get <id> --json
+npx --prefer-offline --yes copilotkit@4.30.0 learning containers get <id> --json
 ```
 
 `"status": "success"` means the container exists. An `error.code` of
@@ -220,6 +238,16 @@ Gather what you need in as few commands as possible. Combine independent reads i
 command rather than running them one at a time. Split a command only when its result decides
 what you run next.
 
+Before you return, record that you are returning:
+
+```text
+npx --prefer-offline --yes copilotkit@4.30.0 onboard checkpoint --phase subagent-returned --brief implement-and-validate --result <ok|failed>
+```
+
+The Status line of your result decides the value. Pass `ok` only for `Status: passed`.
+Pass `failed` for `Status: failed` or `Status: blocked`. If your harness refuses this command, say so in your result and return
+anyway: the main coding agent records it.
+
 Start with `Status: passed`, `Status: failed`, or `Status: blocked`.
 Return exactly four sections: Status, Files changed, Validation, and Blockers. Then end
 your turn.

package/onboarding/prompts/subagent/inspect-repository.md

@@ -8,13 +8,13 @@ Your handoff holds the JSON of this command, which the main coding agent ran fro
 target project directory:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.28.0 onboard inspect --json
+npx --prefer-offline --yes copilotkit@4.30.0 onboard inspect --json
 ```
 
 Read that JSON. Do not run the command again. If the handoff holds no inspection JSON, run
-the command yourself. If your harness refuses it, return at once with no packet. Say that
-the harness refused the command, name it, and do not wait for an approval. That is not
-`Status: blocked`: the main coding agent can run the command and do this work itself.
+the command yourself. If your harness refuses it, return with no packet, as "When a command
+is refused" below says. That is not `Status: blocked`: the main coding agent can run the
+command and do this work itself.
 
 The JSON answers the deterministic half of both packets exactly, from the same code
 `copilotkit verify` uses: the project record by presence, and, for each app or runtime
@@ -48,6 +48,19 @@ target directory that holds no project yet, and `no-declared-dependency` for a p
 where no directory declares one. Report that reason as the finding. Do not report that
 the inspection found nothing.
 
+## When a command is refused
+
+If you are a subagent and your harness refuses a command, return at once. Name the
+command, the directory you ran it from, and the refusal, and run nothing else. Do not wait
+for an approval: nobody sees it. The main coding agent runs the command itself and passes
+the result on. The one wait allowed is a harness escalation request that this brief tells
+you to make for a command. Make that request and wait for its answer.
+
+If your handoff holds a command's result, use it and do not run that command again.
+
+If you are the main coding agent and follow this brief yourself, this section is not for
+you. Do not return: handle a refused command as the run's other prompts say.
+
 ## Project evidence packet
 
 Find evidence for:

package/onboarding/prompts/subagent/prove-oss-baseline.md

@@ -3,6 +3,19 @@
 Read and run only inside the project directory. Do not edit source, configuration,
 dependencies, or tracked files. Do not read, show, store, or return secret values.
 
+## When a command is refused
+
+If you are a subagent and your harness refuses a command, return at once. Name the
+command, the directory you ran it from, and the refusal, and run nothing else. Do not wait
+for an approval: nobody sees it. The main coding agent runs the command itself and passes
+the result on. The one wait allowed is a harness escalation request that this brief tells
+you to make for a command. Make that request and wait for its answer.
+
+If your handoff holds a command's result, use it and do not run that command again.
+
+If you are the main coding agent and follow this brief yourself, this section is not for
+you. Do not return: handle a refused command as the run's other prompts say.
+
 Find the expected agent id from the project. Start the existing agent and frontend only
 when they are not already running. Before using a port, identify its process and working
 directory. Do not stop a process outside this project.
@@ -35,7 +48,7 @@ Prove the live runtime in this order:
 4. Confirm from project files that the runtime constructor passes a `runner` option rather
    than an `intelligence` option. A package, import, project file, or key is not use proof.
 5. Run
-   `npx --prefer-offline --yes copilotkit@4.28.0 verify --expect-runtime oss --round-trip --agent <expected-agent-id> --json`,
+   `npx --prefer-offline --yes copilotkit@4.30.0 verify --expect-runtime oss --round-trip --agent <expected-agent-id> --json`,
    with the runtime URL or auth header options that this project needs. Add
    `--runtime-url <url>` when the report names a runtime URL the dev server does not
    serve. Require exit zero
@@ -68,5 +81,15 @@ The default in-memory OSS runner is ephemeral. SQLite, custom, or framework pers
 can be durable. Report the persistence that project evidence proves, or `unproved`. Do not
 replace it and do not describe all OSS runs as ephemeral.
 
+Before you return, record that you are returning:
+
+```text
+npx --prefer-offline --yes copilotkit@4.30.0 onboard checkpoint --phase subagent-returned --brief prove-oss-baseline --result <ok|failed>
+```
+
+The Status line of your result decides the value. Pass `ok` only for `Status: passed`.
+Pass `failed` for `Status: failed` or `Status: blocked`. If your harness refuses this command, say so in your result and return
+anyway: the main coding agent records it.
+
 Start with `Status: passed`, `Status: failed`, or `Status: blocked`.
 End your turn after returning the baseline result, process ids and ports used, and evidence paths.

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

@@ -50,6 +50,19 @@ Gather what you need in as few commands as possible. Combine independent reads i
 command rather than running them one at a time. Split a command only when its result decides
 what you run next.
 
+## When a command is refused
+
+If you are a subagent and your harness refuses a command, return at once. Name the
+command, the directory you ran it from, and the refusal, and run nothing else. Do not wait
+for an approval: nobody sees it. The main coding agent runs the command itself and passes
+the result on. The one wait allowed is a harness escalation request that this brief tells
+you to make for a command. Make that request and wait for its answer.
+
+If your handoff holds a command's result, use it and do not run that command again.
+
+If you are the main coding agent and follow this brief yourself, this section is not for
+you. Do not return: handle a refused command as the run's other prompts say.
+
 ## Step 1 -- Read what the proof needs
 
 Read all of this from the approved plan in one pass, before you start anything:
@@ -73,10 +86,14 @@ about the failure it was spawned to clear.
 
 ## Steps 2 to 5 -- Run the proof checks
 
+Where your handoff holds an `onboard proof-check` result, that is your first run of the
+proof checks. Read it as the result of the command below. Run the command again only after
+a repair, as the rules below say.
+
 Run this from the target app directory:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.28.0 onboard proof-check --json
+npx --prefer-offline --yes copilotkit@4.30.0 onboard proof-check --json
 ```
 
 It starts each app's `dev` script unless a server from that app already listens, and
@@ -132,7 +149,7 @@ Otherwise sort `firstFailure`, and run the command again after each repair:
   asking. Read the port from the log, not from the plan, and record it:
 
   ```text
-  npx --prefer-offline --yes copilotkit@4.28.0 onboard runtime-url --url <runtime-url>
+  npx --prefer-offline --yes copilotkit@4.30.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
@@ -207,11 +224,20 @@ 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
+before the parent. Wait for its listener to exit before rerunning the proof checks, so
+the command starts only one replacement. Reuse a healthy project-owned frontend instead
+of starting another copy. 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.
 
+Next.js allows only one dev server per project directory. A second `next dev` can
+announce port 3001 and print `Ready` before exiting with `Another next dev server is
+already running` or a `.next/dev/lock` error. Changing ports does not fix that collision.
+Do not delete a live server's lock. Identify the project-owned server and reuse it, or
+stop it under the rule above before rerunning the proof checks. Confirm the replacement
+stays running and serves the app before continuing. Leave other projects' processes alone.
+
 ### Step 5a -- Prove that the page's data reaches the model
 
 Where the proof checks needed `--thread`, the app refuses a run that Steps 5a and 5b send,
@@ -239,7 +265,7 @@ shows it. Send the same run
 body twice: once carrying the context entries the page
 publishes, and once carrying the same entries with one value changed. Use the step 1
 request both times. Write each body to a JSON file in `.copilotkit/proof/`, and send it with
-`npx --prefer-offline --yes copilotkit@4.28.0 verify --send-run <file> --agent <agent id> --json`.
+`npx --prefer-offline --yes copilotkit@4.30.0 verify --send-run <file> --agent <agent id> --json`.
 The command sends the body to `<runtime>/agent/<agent id>/run` and reads the events the run
 streams. It writes them to `<file name>.events.jsonl` beside the body, and prints that path
 with the answer text and the tool calls. Do not send a run with `curl` and read its events
@@ -317,7 +343,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.28.0 verify --round-trip`, which reads the
+that thread with `npx --prefer-offline --yes copilotkit@4.30.0 verify --round-trip`, which reads the
 answer back off the thread and needs no browser. Where the proof checks needed `--thread`,
 prove the thread for this request with `verify --thread <id>` instead. Record which of the
 two you proved.
@@ -347,7 +373,7 @@ 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.28.0 verify --frontend-url <the frontendUrl the proof checks resolved> --json` once,
+`npx --prefer-offline --yes copilotkit@4.30.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
@@ -357,7 +383,7 @@ reach the tool.
    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.28.0 verify --frontend-url <the url you opened> --json`
+   `npx --prefer-offline --yes copilotkit@4.30.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.
@@ -466,6 +492,16 @@ For every other starting state, record Step 8 as not applicable.
 
 ## Step 9 -- Return the result
 
+Before you return, record that you are returning:
+
+```text
+npx --prefer-offline --yes copilotkit@4.30.0 onboard checkpoint --phase subagent-returned --brief prove-round-trip --result <ok|failed>
+```
+
+The Status line of your result decides the value. Pass `ok` only for `Status: passed`.
+Pass `failed` for `Status: failed` or `Status: blocked`. If your harness refuses this command, say so in your result and return
+anyway: the main coding agent records it.
+
 Start with `Status: passed`, `Status: failed`, or `Status: blocked`.
 Use `Status: passed` when the proof attempt completed with `performed`,
 `skipped-no-browser-tool`, `skipped-no-device`, or `skipped-cloned-starter`. The parent

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

@@ -9,9 +9,9 @@ trip caused the route change. Do not say a path works when this release does not
 If the CLI stopped this run with `## Stop: this run deleted or moved the developer's work`,
 name each path and change it listed, in the words it printed. A report that says only that
 files changed cannot be acted on: nobody reading it can tell which file moved.
-This step prints `## The developer's files` below: relay that report as printed, with its
-restore command. When the report says the run started in an empty folder, relay that one
-line alone: list no files and offer no restore.
+This step prints `## Your files` below: relay that report as printed, with its restore
+command. A run that started in an empty folder prints no such section: list no files and
+offer no restore.
 
 Stop onboarding without making more repository changes by default.
 
@@ -36,17 +36,17 @@ Before you show the best-effort plan, require this complete packet:
 Before you end your turn to wait for the developer, report the pause:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.28.0 onboard checkpoint --phase awaiting-developer
+npx --prefer-offline --yes copilotkit@4.30.0 onboard checkpoint --phase awaiting-plan-approval
 ```
 
 After the developer approves the best-effort plan, run
-`npx --prefer-offline --yes copilotkit@4.28.0 onboard read fallback/best-effort`.
+`npx --prefer-offline --yes copilotkit@4.30.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.28.0 onboard friction --phase stop --category <slug> --message "<sentences>"
+npx --prefer-offline --yes copilotkit@4.30.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.28.0",
+  "version": "4.30.0",
   "type": "module",
   "engines": {
     "node": ">=20.9.0"
@@ -19,5 +19,8 @@
   "dependencies": {
     "oidc-provider": "9.12.2"
   },
+  "devDependencies": {
+    "@ag-ui/client": "0.0.57"
+  },
   "license": "SEE LICENSE IN LICENSE"
 }