copilotkit 4.27.0 → 4.28.0

package/README.md

@@ -457,6 +457,10 @@ The fields:
   events do not have it. The total always has it when setup finished.
 - The total carries `duration_ms`, `outcome`, and `phase_count`. A failed setup adds
   `failed_setup_phase`.
+- The total also carries `learning_model`: `configured` when the stack gets a Learning
+  model, or `deferred` when setup ran with `--defer-model` or "configure later". A resumed
+  setup reports the choice it saved. The total has no `learning_model` when setup stopped
+  before the choice was known, for example at the Docker check.
 - A failed setup also adds `failure_reason` to the total and to the failed phase. It is
   a fixed slug that comes from the error's type, never from its message. Examples:
   `docker_unavailable`, `authentication_required`, `memory_short`, `cpu_short`,
@@ -1101,8 +1105,9 @@ It prints one line on stderr that names the run whose backup it is.
 - `onboard credentials` reports the backup as `backup.status`: `ok`, `partial`
   with each path it left out and why, `pending` when the backup waits for
   `onboard start --move`, or `failed` with the cause. A symlink to a file or
-  folder the backup holds does not count as left out. The onboarding plan counts
-  a `partial` or `failed` backup as a risky change and waits for your answer.
+  folder the backup holds does not count as left out. The onboarding plan lists
+  a `partial` or `failed` backup under the changes that need your approval, and
+  waits for your answer.
 
 Backups live in `~/.copilotkit/backups/<run-id>/`, or in
 `$COPILOTKIT_CONFIG_DIR/backups/` when that is set. Besides the current run, the
@@ -1197,10 +1202,11 @@ Outside a repository, `copilotkit init` runs `git init` in the new app and makes
 an initial commit when a git identity is configured, so you have a restore point
 before you start editing.
 
-Inside a repository you already have, it does neither. A second `git init` would
-make the new app a nested repository: commits made in it would go to the inner
-repository, while the outer one saw only an untracked directory. The CLI names
-the repository it found and leaves the new app for you to commit. A repository
+Inside a repository you already have, it does neither. This includes a target
+folder that is a repository itself. A second `git init` would make the new app a
+nested repository: commits made in it would go to the inner repository, while the
+outer one saw only an untracked directory. The CLI names the repository it found,
+commits nothing, and leaves the new app for you to review with `git status`. A repository
 at your home directory, or above it, does not count here, so an app created below
 it gets its own `git init`.
 
@@ -1347,6 +1353,12 @@ wired app returns too. The report shows it as `WARN`, `--json` names it in
 warns when the agent answers without the context value, because a correctly
 wired agent that keeps to its own task answers that way too.
 
+`page_context_reaches_agent` runs after every passing round trip, also for a
+frontend whose files call no context hook. CopilotKit's frontend sends context
+entries of its own, such as the A2UI catalog, and an agent that breaks on
+context fails every browser chat while a plain request still answers. For such a
+frontend, any answer passes, and a run with no answer fails.
+
 With `--json` the payload is the only thing on stdout and every diagnostic goes
 to stderr, so piping is safe.
 
@@ -1382,7 +1394,10 @@ checks.
 2. `"runtimeUrl"` in `.copilotkit/project.json` — an absolute URL for a
    project whose runtime is somewhere none of the below can find it. Add it by
    hand, or let `project select --runtime-url <url>` or
-   `onboard runtime-url --url <url>` write it. The CLI never removes one.
+   `onboard runtime-url --url <url>` write it. The CLI never removes one, but
+   in an onboarding run it can replace one that refuses connections:
+   `verify --round-trip --runtime-url <url>` and `onboard proof-check` can
+   write the new URL. See [`verify` probes port 3000 while the app runs on another port](#verify-probes-port-3000-while-the-app-runs-on-another-port).
 3. `COPILOTKIT_RUNTIME_URL` in the project's `.env` / `.env.local`, when it is
    absolute.
 4. The port the app's own dev configuration declares: `PORT` in its env files,
@@ -1460,10 +1475,33 @@ request in hand is a `resource/request`, and an `info` call never is. A runtime
 below `@copilotkit/runtime` 1.70.2 reports no `singleRoute` block and therefore
 cannot say, so the check is `UNKNOWN` there and names the upgrade.
 
+### Sending one run body and reading its events
+
+`--send-run <file>` sends the AG-UI run body in `<file>` to the agent that
+`--agent` names, and writes the events the run streams to
+`<file name>.events.jsonl` beside it. It runs no check. It prints the answer
+text, the tool calls, and the events path, and exits non-zero when the run did
+not finish or ended in a `RUN_ERROR`.
+
+```bash
+copilotkit verify --send-run .copilotkit/proof/context-run.json --agent incident_triage --json
+```
+
+A runtime wired to Intelligence answers the run with a join token instead of an
+event stream, and the events travel over the realtime gateway. The token is
+single-use and expires 30 seconds after the run starts. The command joins the
+gateway channel as soon as the run answers. If the gateway still refuses the
+token, the command asks the runtime's `/connect` route for a fresh one, once,
+and reads only this run from the channel's replay. Every send gets a new
+`runId`, and a body without `threadId` gets one. A runtime mounted
+`mode: "single-route"` gets the run inside its envelope. A second send of the
+same file replaces its events file. `--timeout` bounds the whole capture
+(default: 90 seconds).
+
 ### Proving the agent runs, not just that it is configured
 
 Every check above describes the project. `--round-trip` makes it work: it sends
-one real request through the runtime and reads the answer back from the thread.
+one real request through the runtime and reads the agent's answer.
 
 ```bash
 copilotkit verify --round-trip
@@ -1471,14 +1509,23 @@ copilotkit verify --round-trip --agent incident_triage      # several declared
 copilotkit verify --round-trip --header "Cookie: session=…" # auth-gated app
 ```
 
-It reads the answer back from `GET /threads/:id/messages` rather than from the
-run's response, because those responses differ by mode. In Intelligence mode the
-run returns a thread lock and a gateway URL, and the agent's events travel to the
-browser over the realtime gateway — so a 200 there proves a run started, which is
-precisely the outcome a runtime that dies mid-turn also produces. Reading the
-thread is one assertion for both modes, and it proves the stronger fact: the
-answer was recorded, not merely emitted. The thread the run reports wins over the
-one the CLI sent, because Intelligence rewrites both ids when it takes the lock.
+In Intelligence mode, the run returns a thread lock, a join token and a gateway
+URL. The agent's events travel over the realtime gateway, on the stream that the
+app's chat shows. `verify` joins that stream as soon as the run answers, and
+reads the answer from it. A 200 on the run proves only that a run started. A
+runtime that stops mid-turn also returns that 200, so the answer itself must
+arrive. The platform saves the thread from the same events later. Under load,
+the saved thread can lag the run by minutes, so it does not decide the verdict.
+
+In four cases, `verify` reads the answer back from `GET /threads/:id/messages`:
+
+- The runtime streams SSE.
+- This Node.js has no `WebSocket`.
+- The gateway refuses the join.
+- The stream ends with no text.
+
+The thread that the run reports wins over the thread that the CLI sent, because
+Intelligence rewrites both ids when it takes the lock.
 
 The assertion is that a non-empty answer came back, never what it said, so the
 verdict does not depend on the model behind the agent. It costs a model call and
@@ -1510,7 +1557,10 @@ no thread. It reads the thread from app-api with the project key, so it needs no
 `--expect-learning-container` checks that same thread. A pass proves that the
 agent's answer was recorded on that thread. It does not prove which end user the
 thread belongs to. A thread app-api does not hold for this project is a `FAIL`.
-Only an answer after the thread's newest user message counts. Inside an
+Only an answer after the thread's newest user message counts. App-api can save
+that answer minutes after the run under load. If the newest user message has no
+answer yet, `--thread` reads the thread again once a second. It waits up to 60
+seconds before it reports a `FAIL`. Inside an
 onboarding run, a thread that did not change after the run started is a `FAIL`,
 because its answer can predate the app as it is now. With `--agent`, a thread
 of another agent is a `FAIL`, and the evidence names the thread's own agent.
@@ -1529,6 +1579,15 @@ the coding agent, decides three things about it:
   to the run's code. `developer` means an answer or an action only the developer
   can give. Where the check started a server, the step carries the last lines of
   its log.
+- A failing `runtime-answers` or `round-trip:agent_answers` check names why in
+  `failureKind`, such as `runtime-timeout`, `run-error`, `run-refused`,
+  `read-refused`, `agent-missing` or `agent-ambiguous`. `run-refused` is a run
+  the runtime refused with 401, 402, 403 or 429. That status usually comes from
+  the Intelligence platform key or the app's own auth, so it names no provider.
+  A failed run whose error carried the provider's own code also names it in
+  `providerError`: `auth`, `quota`, `model-not-found`, `rate-limit` or `other`.
+  It is read from that code, never from a status or a message.
+  `verify --round-trip --json` reports both on `roundTrip` too.
 - When the same check fails three proof checks in a row, the command prints
   `Status: stopped`. A later `onboard proof-check` in the same attempt starts no
   server and prints the same stop. Recording the attempt with `onboard proof`
@@ -1628,10 +1687,30 @@ project record, it writes nothing and exits non-zero.
 Inside an onboarding run, a `verify --round-trip --runtime-url <url>` that
 passes on a runtime other than the recorded one does not count for the run.
 `verify` says so on stderr, and in `roundTripNotRecorded` with `--json`, and
-names this command. `onboard proof` then names that runtime too. The CLI reads
+names this command.
+
+There is one exception. The pass counts, and `verify` writes `<url>` into the
+record, when all of these are true:
+
+- the recorded URL refuses the connection. A timeout, a TLS error, or any
+  answer, even an error, keeps the record;
+- `<url>` is on this machine;
+- a process whose working directory is inside this project listens on the
+  port of `<url>`.
+
+`verify` asks the recorded URL without the `--header` values. In the same
+run, `onboard proof-check` replaces a recorded URL where nothing answers when
+the app's server was already running. It writes the port that server holds. `onboard proof` then names that runtime too. The CLI reads
 `localhost`, `127.0.0.1`, `0.0.0.0`, and `[::1]` on the same port and path as
 one runtime.
 
+`onboard proof-check` restarts a server of the app that started before an env file it reads
+was written, and names the old pids under `servers[].restarted`. After it starts a server, it
+waits up to 90 seconds for the runtime's `/info`. It waits only while nothing answers or the
+server answers with an error, as a dev server does while it compiles. A runtime still not up
+after the wait fails `runtime-answers` with `runtime-not-found`. Any other answer, such as a
+401, goes on to `verify`. `serverWaitMs` says how long the wait took.
+
 ### A model key has no credits or is rejected
 
 A key with no credits passes every static check. The first model call then
@@ -1674,8 +1753,10 @@ the Responses API, which the AI SDK uses. The JSON reports the model as `model`,
 it was set as `modelSource`, and the env file that holds it as `modelFile`. The fix for a
 refused model names that file. The key and the model can live in different files, as in
 the Microsoft Agent Framework Python starter. A model the vendor says it does not serve is a `fail` with
-the cause `model_unavailable`. When the probe passed, the message names the probe model
-as one the same key can use. After the probe passed, a 403 or a spent quota on the app's
+the cause `model_unavailable`. When the probe passed, the message names the model that the
+app's `.env.example` sets in `COPILOTKIT_AGENT_MODEL`, if it is a different model for the same
+vendor. It never names the probe model: the probe sends a plain request, and the app sends
+system messages and page context, so a model that answers the probe can still fail every chat. After the probe passed, a 403 or a spent quota on the app's
 model is `model_unavailable` too: the key works, and Google gives some models no free-tier
 quota. A bare 404 is `undetermined`, because a wrong base URL path answers 404 too. The command reads the variable from the shell first, then from the service whose base URL
 the key goes to, or else from the first service that sets it (see below). The JSON names
@@ -1776,11 +1857,17 @@ It records every answer from the setup message for the bound run, so a later
 step reads it even after the coding agent lost its context:
 
 - `--purpose <text>`, `--framework <name>`, and `--frontend <name>`.
-  `--framework` takes a framework slug or a name from the `setup/questions`
-  table. Another framework's name is recorded as `frameworkName`, with
+  `--framework` takes a framework slug or a name from the framework table that
+  `onboard setup-message --options` lists. Another framework's name is recorded as `frameworkName`, with
   `framework` set to `custom-ag-ui`, the route that builds it. A name close to
   a table row is refused with that row named. Add `--custom-framework` to
-  record it as given.
+  record it as given. A framework recorded before any setup message, for a
+  project with no agent of its own, is kept as a default
+  (`frameworkChoice: default`), because research only inferred it. A provider
+  the developer names later can then replace it with one that takes that
+  provider. Add `--framework-choice developer` for a framework the developer
+  named. A framework recorded with `--vendor-choice existing`, or after the
+  message, is the developer's.
 - `--vendor <openai|anthropic|google|openai-compatible|other>`, with
   `--vendor-choice <developer|default|existing>`. An OpenAI-compatible provider
   also needs `--base-url <url>`, an http or https URL with no user, password, or
@@ -1792,6 +1879,9 @@ step reads it even after the coding agent lost its context:
   (`--connection approved|declined`), and the approval to write to an env file
   or `.copilotkit/project.json` with uncommitted changes
   (`--uncommitted-writes approved|declined`).
+- The env-file answer, when git tracks the env file the key goes into or does
+  not ignore it: `--env-line approved|alternative|declined`.
+  `credentials/finalize-plan` reads it, so the developer is not asked twice.
 
 A later call replaces only the answers it names. The vendor flags replace the
 recorded vendor answer as a whole. With no flag, it prints what the run recorded
@@ -1801,6 +1891,48 @@ must name an existing file. When the key file sets `OPENAI_BASE_URL`, the JSON s
 A free-text answer shaped like a key, such as an `sk-`, `gsk_`, or `AIza` key or
 a long random token, is refused the same way.
 
+`onboard setup-message` writes the setup message the coding agent shows the
+developer. The agent first records what the repository already settles with
+`setup-answers`, then runs it from the target app directory:
+
+```bash
+copilotkit onboard setup-message --target empty --json
+copilotkit onboard setup-message --target empty --options --json
+copilotkit onboard setup-message --target empty --options framework --json
+copilotkit onboard setup-message --target empty --accept-defaults --json
+```
+
+It prints `status`, the `message` to show word for word, the `open` lines, and
+`next`, what the agent does after it:
+
+- `ask`: show `message`, wait, and record the reply. The message puts every
+  default on one line that **go** accepts. The model key is the one question
+  **go** never answers: the developer names the file that holds it, or says
+  "later". The message also holds every line that needs the developer's own
+  answer, such as an env file to untrack or files with uncommitted changes.
+- `settled`: every line is answered. The run goes on to `credentials/plan`.
+- `needs-credentials`: an existing app on the managed route has no project
+  finding yet. The command runs the read-only `onboard credentials` check
+  itself first, so the env-file and project lines go into the one message with
+  the key. Only a check that settles neither line leaves this status, and the
+  agent then runs `onboard credentials --json` itself.
+- `stopped`: that check stopped onboarding. It already filed the stop report,
+  and `stopReason` says why.
+- `needs-toolchain`: the developer chose a framework this machine cannot run
+  yet. The message names what to install, and the run resumes after a restart.
+
+The summary line names every line, the recorded ones too, while one of them
+still holds a default. `--options` shows every line with its recommendation
+first and its likeliest two or three alternatives. `--options <line>`, such as
+`--options framework` or `--options frontend`, lists every choice on that one
+line. `--accept-defaults`
+records the defaults the reply did not change, then prints what is still open.
+`--language <typescript|python|dotnet>` picks the framework for a project with
+no agent, and `--vendor` names a model vendor the developer asked for. A vendor
+the framework does not take becomes a line of its own. On the local route,
+which `onboard deployment` now records, the message holds the Learning model,
+the agreement and the connection lines instead of a project.
+
 Only the developer accepts the local evaluation agreement, in their own
 terminal, with `copilotkit local accept-terms`. The command refuses to run
 without a terminal or when a coding agent runs it. It shows the agreement, its

package/cli-build-info.json

@@ -2,20 +2,20 @@
   "schemaVersion": 1,
   "package": {
     "name": "copilotkit",
-    "version": "4.27.0"
+    "version": "4.28.0"
   },
   "intelligence": {
-    "commit": "85be7ded256d48363acf91081520e5492d5ec0bc"
+    "commit": "a033e00c2995392ce8ace961b4aba1acdf4705f5"
   },
   "copilotKit": {
-    "submittedInput": "3cddb360660503325b24564820c78a2ad7ee1843",
-    "commit": "3cddb360660503325b24564820c78a2ad7ee1843"
+    "submittedInput": "c616389550105d5a96d74501f77c6921aa79ecee",
+    "commit": "c616389550105d5a96d74501f77c6921aa79ecee"
   },
   "channel": "production",
   "triggeringActor": "BenTaylorDev",
   "workflow": {
-    "runId": "38068472728",
-    "runUrl": "https://github.com/CopilotKit/Intelligence/actions/runs/38068472728"
+    "runId": "38464768008",
+    "runUrl": "https://github.com/CopilotKit/Intelligence/actions/runs/38464768008"
   },
   "validationResult": "passed",
   "ag2": {
@@ -24,5 +24,5 @@
     "revision": "main",
     "pinned": false
   },
-  "builtAt": "2026-10-10T16:40:00Z"
+  "builtAt": "2026-10-13T20:42:43Z"
 }