copilotkit 4.25.1 → 4.27.0

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

@@ -26,6 +26,22 @@ bring them into the run root before you report, and name them under Files change
 completion step verifies that the changed files exist in this project, so work left in
 another tree ends the run with nothing in the developer's hands.
 
+<!-- sandboxed-harness -->
+If your harness runs commands in a sandbox, a sandboxed command has no network, cannot
+listen on a port, and cannot connect to localhost. It does not always fail: a package
+install can wait with no output until you stop it. So request escalation on the first run,
+not after a hang or an error, for these commands:
+
+- the dependency install and the Skills install,
+- the commands that start the app and agent servers,
+- HTTP requests to those servers.
+
+Where the harness takes a prefix rule, request one for each command, all at once.
+<!-- /sandboxed-harness -->
+
+If a command hangs with no output, or fails because it has no network or cannot listen on a
+port, a sandbox probably blocked it. Stop it and run it again with escalation.
+
 Before validation, inspect the current changed and untracked paths. Leave out the paths that
 were already changed or untracked when the run started and that this run did not edit.
 Compare every other changed path with the paths the plan named. If a changed path
@@ -84,6 +100,9 @@ Wiring is not behavior. Add the CopilotKit SDK dependency, wrap the agent in the
 middleware, mount the runtime, connect AG-UI, and render what the agent already returns.
 Those are the parts this run adds.
 
+A run whose `environmentPath` ends in `.env.local` hosts the CopilotKit runtime in that
+Next.js app, never in a separate server: no other process reads the key from that file.
+
 A change on the behavior list changes how the agent answers everywhere, not only in
 CopilotKit, so the developer approves it before it is written. Where a step cannot be
 built without one the plan did not name, return `Status: blocked` and name the file, the
@@ -110,7 +129,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.25.1 onboard upgrade-plan --check --json
+npx --prefer-offline --yes copilotkit@4.27.0 onboard upgrade-plan --check --json
 ```
 
 `single` means every direct dependency resolved to one version. `duplicates` names each
@@ -125,7 +144,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.25.1 onboard upgrade-plan --revert --json
+npx --prefer-offline --yes copilotkit@4.27.0 onboard upgrade-plan --revert --json
 ```
 
 Then end your turn. Never add an `overrides`, `resolutions`, or `pnpm.overrides` block to
@@ -161,7 +180,7 @@ Where the plan names a Learning Container id, check that the container exists fi
 this from the target app directory, before you write any selector:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.25.1 learning containers get <id> --json
+npx --prefer-offline --yes copilotkit@4.27.0 learning containers get <id> --json
 ```
 
 `"status": "success"` means the container exists. An `error.code` of
@@ -185,19 +204,19 @@ Where the plan names no container, write no selector.
 
 ## Install the CopilotKit Skills
 
-The main coding agent gives you the developer's answer on the Skills install. Where the
-whole-plan implementation handoff carries no answer, read the approved plan. Approving the
-plan without a word on the Skills approves the install. A repair handoff that carries no
-Skills answer never installs them.
+The plan names the Skills install on its own line, and the build does not wait for an
+answer on it. Install them in a whole-plan implementation. Skip it only when the developer
+said no, which the main coding agent passes in the handoff. A repair handoff never installs
+them.
 
 Where `.agents/skills` already holds the CopilotKit skills, do not install them again.
 Report that they are in place.
 
-Install the Skills only when the developer approved them. Where the developer declined
-them, do not install them, and do not call that a change from the plan. Report in the
-Validation section that the developer declined them.
+Where the developer said no, do not install them, and do not call that a change from the
+plan. Report in the Validation section that the developer declined them.
 
-Install them after you run the full validation list. Tell the developer what the skills
+Install them at the same time as the project's dependencies, not after validation: start both installs together. Where this run installs no dependencies,
+install them before you run the validation list. Tell the developer what the skills
 install writes into this project before you run it: a `.agents/skills` directory holding
 one folder per CopilotKit skill, linked into `.claude/skills`. Both sit in the working tree,
 so the install shows up in `git status` and can land in a commit. You cannot know whether
@@ -206,9 +225,9 @@ rather than after.
 
 Then run `npx skills add CopilotKit/CopilotKit/skills -y` in the target app directory.
 
-The plan names both directories under `Files the run writes itself`, so they are not
-departures. Name them under Files changed. Do not register an MCP server: the Skills read
-the CopilotKit documentation without one.
+The plan names both directories under `Skills install`, so they are not departures. Name
+them under Files changed. Do not register an MCP server: the Skills read the CopilotKit
+documentation without one.
 
 Check whether the install succeeded, and record the command result in the Validation
 section. A failed install does not change your status. Report it and continue.

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

@@ -8,7 +8,7 @@ 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.25.1 onboard inspect --json
+npx --prefer-offline --yes copilotkit@4.27.0 onboard inspect --json
 ```
 
 Read that JSON. Do not run the command again. If the handoff holds no inspection JSON, run
@@ -58,7 +58,8 @@ Find evidence for:
   `detection` block the CLI proposed
 - for an existing agent in no listed framework, whether it speaks AG-UI: a class that
   extends `AbstractAgent` and implements `run`, or an endpoint that streams AG-UI events.
-  Cite the file
+  If it does not, name its entry point: the function or HTTP route that runs it. Cite the
+  file
 - current CopilotKit integration and configuration
 - authentication boundaries
 - initial changed and untracked paths, without file contents

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

@@ -13,12 +13,15 @@ instance of next dev running?`. A free port does not help. If a `next dev` proce
 runs from this app, reuse that server. Prove against its port. If a start still fails with
 that message, name the process that holds the lock. Give its PID and working directory.
 
+<!-- sandboxed-harness -->
 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.
+escalation with a prefix rule for `curl`.
+<!-- /sandboxed-harness -->
+If a local request fails after 0 ms (`Failed to connect ... after 0 ms`) while the port
+shows a listener, a sandbox blocked it. Run it again with escalation, and do not record a
+failed predicate or step.
 
 Prove the live runtime in this order:
 
@@ -32,8 +35,10 @@ 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.25.1 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
+   `npx --prefer-offline --yes copilotkit@4.27.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
    and the JSON `ok` field to be `true`.
 6. Drive one real request through the existing frontend, CopilotKit runtime, and expected
    agent. Require the existing user-visible result.

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

@@ -25,7 +25,8 @@ render, and never report a round trip proved by a prompt this run rewrote.
 
 Run the steps below in the order they appear. They are the proof. Do not design a
 different sequence of your own, and do not drop a step because an earlier one looked
-convincing. Step 6 has a web form and a React Native form: run the one that matches this
+convincing. A check that passed is the evidence for what it checks. Send only the requests
+the steps name: no SDK calls, AG-UI requests, or thread reads of your own to confirm a pass. Step 6 has a web form and a React Native form: run the one that matches this
 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
@@ -75,7 +76,7 @@ about the failure it was spawned to clear.
 Run this from the target app directory:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.25.1 onboard proof-check --json
+npx --prefer-offline --yes copilotkit@4.27.0 onboard proof-check --json
 ```
 
 It starts each app's `dev` script unless a server from that app already listens, and
@@ -88,8 +89,12 @@ It starts only the apps that depend on CopilotKit. If the agent runs somewhere e
 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.
+does not start an app inside that directory a second time.
+<!-- sandboxed-harness -->
+If your harness runs commands in a sandbox, request escalation for this command on its
+first run: it starts servers and connects to localhost. Request a prefix rule for `curl`
+in the same request, because Steps 5a and 5b send local requests too.
+<!-- /sandboxed-harness -->
 
 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
@@ -97,8 +102,9 @@ project named no port the CLI can read: take the URL from the frontend server's
 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.
+project. Read the agent IDs the runtime declares from the `verify:runtime_agents_declared`
+detail, and compare them with the expected agent ID from Step 1. Do not send a request of
+your own for them. 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. On Windows, and in a container that hides which process
 holds a port, the CLI cannot read the port's owner. There `runtime-process-in-project` is
@@ -126,7 +132,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.25.1 onboard runtime-url --url <runtime-url>
+  npx --prefer-offline --yes copilotkit@4.27.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
@@ -296,7 +302,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.25.1 verify --round-trip`, which reads the
+that thread with `npx --prefer-offline --yes copilotkit@4.27.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.
@@ -326,7 +332,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.25.1 verify --frontend-url <the frontendUrl the proof checks resolved> --json` once,
+`npx --prefer-offline --yes copilotkit@4.27.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
@@ -336,7 +342,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.25.1 verify --frontend-url <the url you opened> --json`
+   `npx --prefer-offline --yes copilotkit@4.27.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.
@@ -448,7 +454,7 @@ Step 9 can write only the tool files named by its guide or by this step.
 Fetch the continued-development guide from the main coding agent with the proof
 documentation. Try the continued-development tools after the application passes proof.
 
-The implementation subagent installs the Skills when the developer approved them. Check that
+The implementation subagent installs the Skills unless the developer declined them. Check that
 it did. Look for the `.agents/skills` directory and the `.claude/skills` links in this
 project, and read the Skills result the implementation reported. Do not install them again.
 
@@ -456,15 +462,18 @@ Where the developer declined them, do not install them, and do not call that a c
 the plan. Report the command for them to run later instead:
 `npx skills add CopilotKit/CopilotKit/skills -y`.
 
-Where the developer approved them and they are missing, install them as a recovery step.
+Where the developer did not decline them and they are missing, install them as a recovery step.
 Tell the developer what the skills install writes into this project before you run it: a
 `.agents/skills` directory holding one folder per CopilotKit skill, linked into
 `.claude/skills`. Both sit in the working tree, so the install shows up in `git status`
 and can land in a commit. You cannot know whether this project keeps those directories in
 version control, so name them before you write them rather than after. Then run
 `npx skills add CopilotKit/CopilotKit/skills -y` to install the
-project-scoped CopilotKit Skills. Record that the proof ran the install because the
-implementation did not.
+project-scoped CopilotKit Skills.
+<!-- sandboxed-harness -->
+It needs the network, so in a sandbox request escalation for it on its first run.
+<!-- /sandboxed-harness -->
+Record that the proof ran the install because the implementation did not.
 
 Do not register an MCP server: the Skills read the CopilotKit documentation without one.
 

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

@@ -10,7 +10,8 @@ If the CLI stopped this run with `## Stop: this run deleted or moved the develop
 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.
+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.
 
 Stop onboarding without making more repository changes by default.
 
@@ -35,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.25.1 onboard checkpoint --phase awaiting-developer
+npx --prefer-offline --yes copilotkit@4.27.0 onboard checkpoint --phase awaiting-developer
 ```
 
 After the developer approves the best-effort plan, run
-`npx --prefer-offline --yes copilotkit@4.25.1 onboard read fallback/best-effort`.
+`npx --prefer-offline --yes copilotkit@4.27.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.25.1 onboard friction --phase stop --category <slug> --message "<sentences>"
+npx --prefer-offline --yes copilotkit@4.27.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.25.1",
+  "version": "4.27.0",
   "type": "module",
   "engines": {
     "node": ">=20.9.0"

package/release/release-tool.js

@@ -14931,7 +14931,7 @@ var FLAG_DEFINITIONS = defineFlags({
   // 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 capture, saved reads, and Trajectory sessions as a Learning source in app-api, the realtime gateway, the web app, and the Learning scheduler and runners.",
+    purpose: "Gates Trajectory capture, saved reads, live viewing, and Trajectory sessions as a Learning source in app-api, the realtime gateway, the web app, and the Learning scheduler and runners. Live viewing also requires learning.trajectory-live-view.",
     owner: "learning",
     createdAt: "2026-10-01",
     status: "rollout",
@@ -14944,6 +14944,16 @@ var FLAG_DEFINITIONS = defineFlags({
     ],
     defaultByEnv: { dev: true, ci: true, prod: false }
   },
+  // Keep existing capture deployments on saved reads until every API and gateway
+  // replica supports live viewing and descending history. CI exercises both paths.
+  "learning.trajectory-live-view": {
+    purpose: "Enables operator live viewing and newest-first history after app-api and every realtime gateway replica support them.",
+    owner: "learning",
+    createdAt: "2026-10-09",
+    status: "rollout",
+    surfaces: ["app-api", "realtime-gateway", "app-frontend"],
+    defaultByEnv: { dev: false, ci: true, prod: false }
+  },
   "analytics.pipeline": {
     purpose: "Gates project-scoped analytics reads and realtime projection while the durable pipeline rolls out.",
     owner: "analytics",
@@ -14974,7 +14984,7 @@ init_define_CLI_LOCAL_EVALUATION_SUPPORT();
 
 // apps/cli/src/config.ts
 function getTemplateRef() {
-  return true ? "6c428329c9b81b3aa7e92b602ab1c0a9431d36a3" : "main";
+  return true ? "3cddb360660503325b24564820c78a2ad7ee1843" : "main";
 }
 
 // apps/cli/src/services/agentcore-config.ts