copilotkit 4.23.0 → 4.24.0

package/onboarding/prompts/starter/clone.md

@@ -55,7 +55,7 @@ the derived name.
 Only if the developer asks for an existing project, or asks to see the projects they have,
 read the choices:
 
-`npx --prefer-offline --yes copilotkit@4.23.0 project list --json`
+`npx --prefer-offline --yes copilotkit@4.24.0 project list --json`
 
 Then ask which one to use. Do not order the projects by creation time. If the developer
 already gave this answer, do not ask again. Do not read a secret value. Do not show or
@@ -84,7 +84,7 @@ Do not inspect another entry in the parent directory. Replace each placeholder w
 recorded value. Do not run a placeholder as a shell argument. If the path holds a space,
 put it in double quotes.
 
-`npx --prefer-offline --yes copilotkit@4.23.0 init --dir <absolute-target-directory> --framework <framework-id> --channel none --no-banner --no-key-prompt --create <name> --install`
+`npx --prefer-offline --yes copilotkit@4.24.0 init --dir <absolute-target-directory> --framework <framework-id> --channel none --no-banner --no-key-prompt --create <name> --install`
 
 `--dir` is always the absolute path of the target directory. `init` builds the app in that
 directory and gives the app the directory's name. Do not add `--name`: `init` refuses
@@ -102,9 +102,64 @@ variable name and never the value. Do not read or copy the key file yourself. If
 reports that it cannot read the model key file, it stopped before it cloned anything. Ask
 the developer for the right path, or run the command again without the flag.
 
+If you cannot pass the key file to `init`, for example because a sandbox refuses the path,
+clone without `--model-key-file`. Then copy the key from `<target>` with one command:
+`cd <target> && npx --prefer-offline --yes copilotkit@4.24.0 onboard credentials --model-key <VARIABLE> --env-path <key-file> --copy-to <env file> --json`.
+`<env file>` is `.env`, or `agent/.env` for the Microsoft Agent Framework Python starter.
+The command writes the key into that file without printing it and protects the file. If the
+command is refused too, ask the developer to run it. Give them exactly this one line:
+`! cd <target> && npx --prefer-offline --yes copilotkit@4.24.0 onboard credentials --model-key <VARIABLE> --env-path <key-file> --copy-to <env file>`.
+The command needs no input. Without `!`, they run the same command in a terminal.
+Do not write a `sed`, `grep`, or `cat` command to copy the key.
+
+### For a recorded local choice
+
+If the run recorded the local deployment choice in `deployment/choose-local`, use this
+command instead of the hosted command above. Do not ask the project questions above.
+Local evaluation creates its own empty project, and `init --local` refuses `--create` and
+`--project`.
+
+`npx --prefer-offline --yes copilotkit@4.24.0 init --dir <absolute-target-directory> --framework <framework-id> --channel none --no-banner --no-key-prompt --local --defer-model --install`
+
+Use the model choice from `deployment/choose-local`. If the developer deferred it, keep
+`--defer-model`. If the developer gave model settings, replace `--defer-model` with
+`--model-config <private-file>`. Do not read or print that file. The CLI selects the latest
+stable release. If the developer gave a candidate manifest for release testing, add
+`--candidate <manifest.json>`. Otherwise, do not add it. The `--dir`, `--no-install` and `--model-key-file` rules
+above apply here too.
+
+If the developer chose guided model setup in `deployment/choose-local`, keep `--defer-model`.
+After `init` reports the stack ready:
+
+Ask the developer to run this command in their own terminal window, in `<target>`:
+
+```text
+npx --prefer-offline --yes copilotkit@4.24.0 local setup
+```
+
+Do not give it as a `!` line, and do not run it yourself. Its guided model prompt needs a
+terminal, and a coding agent's shell has none. Without a terminal, the command stops and
+changes nothing. The prompt asks for the model and its key, and it saves them privately.
+On a running stack, it restarts only Learning. Do not ask for a model file.
+
+Say that the run continues when they reply or resume this session. Report the pause with
+`npx --prefer-offline --yes copilotkit@4.24.0 onboard checkpoint --phase awaiting-model-credential`, end your
+turn, and wait. When the developer replies, run
+`npx --prefer-offline --yes copilotkit@4.24.0 local status --json` from `<target>` and read `learning.configuration`.
+
+The command installs the local stack, then connects the starter to it. It writes the
+gitignored `.copilotkit/local.json` stack reference and `.copilotkit/project.json` with the
+local project. It writes `INTELLIGENCE_API_URL`, `INTELLIGENCE_GATEWAY_WS_URL`,
+`CPK_INTELLIGENCE_API_KEY` and `SL_ENABLED` into `<target>/.env`. Later proof steps use
+this local project. Do not run `project select`, and do not provision another key. The
+output names the local dashboard URL. If you deferred the model, the output also says
+`Learning configuration incomplete`. Report both lines to the developer.
+
+### What the command does
+
 The command clones the starter into the empty target directory. It also connects the
-starter to the developer's Intelligence project. The earlier login phase supplies the
-account. The command does not need terminal input.
+starter to the developer's Intelligence project, or to the local stack for a local choice.
+The earlier login phase supplies the account. The command does not need terminal input.
 
 Do not rebuild the starter by hand. Then inspect only the generated
 paths inside the target directory. Record the files, install result, project connection,
@@ -144,7 +199,7 @@ When you ask, name each variable and the file it goes in, and say that the run c
 when they reply or resume this session. Then report the pause and end your turn:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.23.0 onboard checkpoint --phase awaiting-model-credential
+npx --prefer-offline --yes copilotkit@4.24.0 onboard checkpoint --phase awaiting-model-credential
 ```
 
 This is a pause, not a stop. Do not send a stop report, and do not take a stop route.
@@ -155,10 +210,40 @@ call.
 
 If no credential is missing, report no pause and continue.
 
-Then run `npx --prefer-offline --yes copilotkit@4.23.0 onboard read proof/round-trip`.
+Then run `npx --prefer-offline --yes copilotkit@4.24.0 onboard read proof/round-trip`.
+
+If the local command fails, `init` keeps the cloned starter in `<target>`. Do not run
+`init` again, because the target is no longer empty. Do not delete the starter or the stack.
+Report the exact error, and do not claim that the starter is ready. A failure that names
+Docker is an environment blocker, not a broken run. For example, Docker is stopped or
+missing, or `Docker available resources` is below 4 CPUs, 12 GiB RAM, or 40 GiB storage.
+Tell the developer what to change in Docker. Then report the pause and end your turn:
+
+```text
+npx --prefer-offline --yes copilotkit@4.24.0 onboard checkpoint --phase awaiting-developer
+```
+
+When the developer says that Docker is ready, resume from `<target>` with the same model
+choice. If the run used a `--candidate`, add the same one:
+
+```text
+npx --prefer-offline --yes copilotkit@4.24.0 local setup --defer-model --json
+```
+
+If the run used model settings, replace `--defer-model` with `--model-config <private-file>`.
+Read blockers and the recorded failed step. Do not delete or recreate a failed stack. After
+setup reports the stack ready, connect the starter from `<target>`:
+
+```text
+npx --prefer-offline --yes copilotkit@4.24.0 local connect --approve-connection --json
+```
+
+The connection writes `.copilotkit/local.json`, `.copilotkit/project.json`, and the local
+keys in `<target>/.env`. Then continue with the credential check above. If the resumed
+setup fails again with an error that does not name Docker, take the route below.
 
 If the command fails, report its exact error and do not claim that the starter is ready.
 Then run
-`npx --prefer-offline --yes copilotkit@4.23.0 onboard read stopped/run-failed`. The starter is one this
+`npx --prefer-offline --yes copilotkit@4.24.0 onboard read stopped/run-failed`. The starter is one this
 graph ships and the stack was chosen from its own supported list, so a command that
 returned an error is a run that broke, not a setup this release does not support.

package/onboarding/prompts/stopped/run-failed.md

@@ -41,7 +41,7 @@ put to them, stop here and send the report below.
 If they approve it, make that one fix and nothing else. Then come back into this run:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.23.0 onboard resume --message "<approval>"
+npx --prefer-offline --yes copilotkit@4.24.0 onboard resume --message "<approval>"
 ```
 
 Put the developer's approval in `--message`, in one or two sentences: the fix they
@@ -64,7 +64,7 @@ Send one short report. The friction command follows the telemetry setting the de
 already chose, so it needs no separate question.
 
 ```text
-npx --prefer-offline --yes copilotkit@4.23.0 onboard friction --phase stop --category <slug> --message "<sentences>"
+npx --prefer-offline --yes copilotkit@4.24.0 onboard friction --phase stop --category <slug> --message "<sentences>"
 ```
 
 `--message` takes one or two sentences: the step you stopped at and what stopped

package/onboarding/prompts/subagent/create-plan.md

@@ -94,7 +94,7 @@ against a dead host, and the failure arrives as an empty-body 404 with no cause
 Ask the CLI for the dependency upgrade, from the target directory:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.23.0 onboard upgrade-plan --json
+npx --prefer-offline --yes copilotkit@4.24.0 onboard upgrade-plan --json
 ```
 
 It reads the installed tree and the registry. Read `status`:
@@ -176,7 +176,7 @@ here is work the developer did not ask for.
 Plan the threads drawer itself: add it from the selected drawer page, where this frontend
 does not already render one. Where this journey's frontend framework ships no threads
 drawer -- React Native --, plan that the thread is proved by
-`npx --prefer-offline --yes copilotkit@4.23.0 verify --round-trip`, which needs no browser. Do not plan a
+`npx --prefer-offline --yes copilotkit@4.24.0 verify --round-trip`, which needs no browser. Do not plan a
 step that opens the managed Intelligence dashboard.
 
 ## Name the files the run writes itself

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

@@ -115,7 +115,7 @@ Intelligence: declare each exact version in its app's manifest, then install wit
 project's package manager. Then check the installed tree:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.23.0 onboard upgrade-plan --check --json
+npx --prefer-offline --yes copilotkit@4.24.0 onboard upgrade-plan --check --json
 ```
 
 `single` means every direct dependency resolved to one version. `duplicates` names each
@@ -130,7 +130,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.23.0 onboard upgrade-plan --revert --json
+npx --prefer-offline --yes copilotkit@4.24.0 onboard upgrade-plan --revert --json
 ```
 
 Then end your turn. Never add an `overrides`, `resolutions`, or `pnpm.overrides` block to

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

@@ -7,7 +7,7 @@ Work only on the packet you were assigned. Inspect the repository without changi
 Run this first, from the target project directory:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.23.0 onboard inspect --json
+npx --prefer-offline --yes copilotkit@4.24.0 onboard inspect --json
 ```
 
 It answers the deterministic half of both packets exactly, from the same code

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

@@ -32,7 +32,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.23.0 verify --expect-runtime oss --round-trip --agent <expected-agent-id> --json`,
+   `npx --prefer-offline --yes copilotkit@4.24.0 verify --expect-runtime oss --round-trip --agent <expected-agent-id> --json`,
    with the runtime URL or auth header options that this project needs. Require exit zero
    and the JSON `ok` field to be `true`.
 6. Drive one real request through the existing frontend, CopilotKit runtime, and expected

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

@@ -78,7 +78,7 @@ about the failure it was spawned to clear.
 Run this from the target app directory:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.23.0 onboard proof-check --json
+npx --prefer-offline --yes copilotkit@4.24.0 onboard proof-check --json
 ```
 
 It starts each app's `dev` script unless a server from that app already listens, and
@@ -103,7 +103,9 @@ A pass on `runtime-process-in-project` proves only that the process runs inside
 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.
+the proof. Then go to Step 5a. On Windows, `runtime-process-in-project` is `undetermined` and
+marked `advisory`, because the CLI cannot read Windows processes. The checks still pass. Ask
+the agent ID question all the same.
 
 Otherwise sort `firstFailure`, and run the command again after each repair:
 
@@ -114,7 +116,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.23.0 onboard runtime-url --url <runtime-url>
+  npx --prefer-offline --yes copilotkit@4.24.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
@@ -249,7 +251,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.23.0 verify --round-trip`, which reads the
+that thread with `npx --prefer-offline --yes copilotkit@4.24.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
@@ -277,7 +279,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.23.0 verify --frontend-url <the frontendUrl the proof checks resolved> --json` once,
+`npx --prefer-offline --yes copilotkit@4.24.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
@@ -287,7 +289,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.23.0 verify --frontend-url <the url you opened> --json`
+   `npx --prefer-offline --yes copilotkit@4.24.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.23.0 onboard read fallback/best-effort`.
+`npx --prefer-offline --yes copilotkit@4.24.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.23.0 onboard friction --phase stop --category <slug> --message "<sentences>"
+npx --prefer-offline --yes copilotkit@4.24.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.23.0",
+  "version": "4.24.0",
   "type": "module",
   "engines": {
     "node": ">=20.9.0"

package/release/release-tool.js

@@ -14916,6 +14916,17 @@ var FLAG_DEFINITIONS = defineFlags({
     defaultByEnv: { dev: false, ci: false, prod: false },
     envVar: "LEARNING_ENABLED"
   },
+  // Product Trajectories v0.1: app-api mints Trajectory join tokens and the
+  // gateway stores browser event batches. Both surfaces read the derived
+  // FF_LEARNING_TRAJECTORIES override; the gateway mirrors the env default.
+  "learning.trajectories": {
+    purpose: "Gates Trajectory join tokens, operator read APIs, and the web app capability in app-api, and browser event capture on the realtime gateway.",
+    owner: "learning",
+    createdAt: "2026-10-01",
+    status: "rollout",
+    surfaces: ["app-api", "realtime-gateway", "app-frontend"],
+    defaultByEnv: { dev: true, ci: true, prod: false }
+  },
   "analytics.pipeline": {
     purpose: "Gates project-scoped analytics reads and realtime projection while the durable pipeline rolls out.",
     owner: "analytics",
@@ -14946,7 +14957,7 @@ init_define_CLI_LOCAL_EVALUATION_SUPPORT();
 
 // apps/cli/src/config.ts
 function getTemplateRef() {
-  return true ? "f835ce816112541654ded07162c2cc8ddf4f3f2c" : "main";
+  return true ? "c88a2dd2a4c024e956e3f88b6b86d5715951e284" : "main";
 }
 
 // apps/cli/src/services/agentcore-config.ts