copilotkit 4.9.17 → 4.9.31

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

@@ -35,13 +35,40 @@ reference naming hosts that route nothing, and it requires the platform URLs the
 documentation calls optional. A run that reads that reference configures the runtime
 against a dead host, and the failure arrives as an empty-body 404 with no cause named.
 
-If any `@copilotkit/*` dependency is below 1.64.0, plan to upgrade every `@copilotkit/*`
+If any `@copilotkit/*` dependency is below 1.70.0, plan to upgrade every `@copilotkit/*`
 dependency to its latest published version. Packages that share a version line must end
 on the same version. Never force a package onto a version line it does not publish on.
 Resolve each latest version at run time rather than from a remembered version number.
 Where every `@copilotkit/*` dependency already meets that floor, plan no dependency
 change.
 
+The floor is 1.70.0 because the runtime resolves managed Intelligence entitlement
+authority from that version. A runtime below it reports its license from a self-hosted
+token alone. A managed project holds no such token, so the threads drawer this conversion
+adds lists nothing even after every command-line check passes.
+
+The upgrade moves more than the `@copilotkit/*` namespace. Intersect the dependencies the
+app declares directly with what the target `@copilotkit/*` versions require, and name in the
+plan every one whose declared range excludes the version the target needs, with the version
+it moves to. The `@ag-ui/*` packages are the CopilotKit protocol layer, on their own version
+line, so they are the ones this meets most often, but the rule is the intersection rather
+than that namespace.
+
+The intersection includes what a `@copilotkit/*` package on its own version line declares
+about the `1.x` line. `@copilotkit/angular` is the one that has this, and its declaration
+is materialized at publish time rather than written in the repository, so read it from the
+registry rather than from any checkout. Where it cannot be satisfied by the version the
+floor requires, there is no upgrade to plan: that is `unsupported/no-validated-path`.
+
+An exact pin is usually deliberate. Naming the move here is what makes it a step the
+developer approved rather than a repair the run invents halfway through. Do not move a pin
+the developer did not approve moving. Where the developer needs one held, that is
+`unsupported/no-validated-path`, and the upgrade step's revert is the way back.
+
+Name the exact version the target requires. A caret does not stand in for it below `0.1.0`:
+`^0.0.59` admits only `0.0.59`, so a pin rewritten that way is the same pin under a
+different spelling, and it breaks again as soon as CopilotKit moves to `0.0.60`.
+
 Plan the upgrade as its own step before the Intelligence runtime wiring, and plan to
 re-run the recorded baseline checks immediately after it. Name the revert: restore the
 manifest and lockfile to their recorded state and stop, rather than wiring Intelligence
@@ -94,8 +121,9 @@ 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 in the managed Intelligence
-dashboard instead.
+drawer -- React Native --, plan that the thread is proved by
+`npx --yes copilotkit@4.9.31 verify --round-trip`, which needs no browser. Do not plan a
+step that opens the managed Intelligence dashboard.
 
 ## Order the plan into steps
 

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

@@ -51,7 +51,36 @@ Where the plan names a CopilotKit dependency upgrade:
 
 1. Apply the planned CopilotKit dependency upgrade before you wire Intelligence.
 2. Report each `@copilotkit/*` version before and after the upgrade.
-3. Then re-run the recorded baseline checks.
+3. Prove that every dependency the app declares directly resolves to exactly one version in
+   the installed tree.
+4. Then re-run the recorded baseline checks.
+
+The package manager does not fail on this. Where the app pins a package exactly and the
+upgraded CopilotKit needs a different version of it, npm keeps the pin at the top of the
+tree and nests the other copy, so the install exits zero and `--dry-run` shows nothing.
+Two copies of a package that carries types fail the type check in some field that has
+nothing to do with either version, so the developer reads it as a bug in their own code.
+Read the installed tree, not the manifest: ask the package manager how many versions of
+each direct dependency it resolved, with `npm ls <name>`, `pnpm why <name>`, or the
+equivalent for the lockfile this project uses. Direct dependencies are a short list, and
+they are the ones whose duplicate breaks a build, so this catches `react`, `zod`,
+`graphql`, and the next protocol package as well as `@ag-ui/*`.
+
+`@copilotkit/*` counts here, not only third-party packages. `@copilotkit/angular`
+publishes on a version line of its own and declares a `@copilotkit/core` chosen when that
+Angular release was cut, so the upgrade can install one `@copilotkit/core` while the
+Angular package demands another. That is the case this catches most expensively, because
+it fails in the threads drawer rather than at the install.
+
+If one of them resolves to more than one version, restore the manifest and lockfile to
+their recorded state, leave Intelligence unwired, and report which package resolved to more
+than one version, which versions, and which declared range held the top of the tree. Stop.
+Do not wire Intelligence onto a tree carrying two copies of a package.
+
+Never add an `overrides`, `resolutions`, or `pnpm.overrides` block to collapse the two
+copies. It forces a version the developer did not approve onto their whole tree, and it
+turns a reportable mismatch between two published packages into a local workaround nobody
+else can see.
 
 If the baseline regresses, restore the manifest and lockfile to their recorded state, leave
 Intelligence unwired, and report the regression with the failing check. Stop. Where the plan

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

@@ -38,7 +38,7 @@ from different directories.
 
 For the CopilotKit versions, report the exact installed version of every `@copilotkit/*`
 dependency, read from the lockfile rather than a manifest range, and state whether any of
-them is below 1.64.0. The conversion decides its upgrade from exactly that, and a caret
+them is below 1.70.0. The conversion decides its upgrade from exactly that, and a caret
 range does not answer it.
 
 A project states what it is for in its `README.md`, in its package description, or in

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

@@ -16,17 +16,26 @@ 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 --yes copilotkit@4.9.17 verify --expect-runtime oss --round-trip --agent <expected-agent-id> --json`,
+   `npx --yes copilotkit@4.9.31 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
-   agent. Require the existing user-visible result. If no browser tool is available, the
-   round trip is not proved and the state is `unproved`.
+   agent. Require the existing user-visible result.
 
-Classify the state as `both-oss` only when all six predicates are true: agent present,
-interface present, CopilotKit present, CopilotKit round trip proven, runtime connection
-`oss`, and managed Intelligence not configured. Return each predicate and its secret-safe
-evidence.
+Use the surface control the main coding agent recorded for your environment. It either had
+one already or registered one before this step, so that finding is the answer and there is
+nothing here for you to go looking for. Do not add a browser or device driver to this
+project: a devDependency and a browser download land in the diff of a repository that never
+asked for one, which is a different thing from a server registered against the coding agent.
+Where the recorded control is `unavailable`, record predicate 6 as skipped, with that as the
+reason, and prove the rest.
+
+Classify the state as `both-oss` when predicates 1 to 5 are all true. Predicate 5 proves the
+CopilotKit round trip from a shell, so those five settle the starting state on their own.
+Predicate 6 adds the user-visible surface on top of a state already proved: record it as
+passed, failed, or skipped, and do not withhold `both-oss` for a skip. A failed predicate 6
+on an available surface is a baseline failure and is not a skip. Return each predicate and
+its secret-safe evidence.
 
 The default in-memory OSS runner is ephemeral. SQLite, custom, or framework persistence
 can be durable. Report the persistence that project evidence proves, or `unproved`. Do not

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

@@ -90,8 +90,8 @@ A server that never answered has written the reason to its own output, and readi
 output is faster than starting it again.
 
 Leave the agent and frontend servers running after proof. Record each process ID and a
-safe command that stops that process. Record the frontend URL and the commands that start
-both servers again.
+safe command that stops that process. Record the frontend URL, written with `localhost`
+rather than an IP literal, and the commands that start both servers again.
 
 ## Step 3 -- Identify the process that answered
 
@@ -120,15 +120,25 @@ 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 --yes copilotkit@4.9.17 verify --json`. Add `--runtime-url` when the runtime is not at
-`http://localhost:3000/api/copilotkit`. 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.
+`npx --yes copilotkit@4.9.31 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 pass
+`--runtime-url` with the URL from step 1 in that case. 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. Write the key there, or run
+`npx --yes copilotkit@4.9.31 project select` from the app directory. 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 handler
 mounted `mode: "single-route"` is the usual cause. Return it for implementation to remove the
 option and use a catch-all route. Do not edit it. If the check is `undetermined` because no
@@ -136,7 +146,7 @@ thread-endpoint state exists, the runtime predates the field. Record that and co
 
 ## Step 5 -- Prove that the agent runs
 
-Run `npx --yes copilotkit@4.9.17 verify --round-trip --json`. It sends one request through
+Run `npx --yes copilotkit@4.9.31 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
@@ -212,8 +222,9 @@ journey, and the graph ends such a run as blocked rather than complete.
 For a recorded `both-oss` starting state, this step has no component to render. Send the
 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 --, find
-that thread in the managed Intelligence dashboard and record which of the two you proved.
+Where this journey's frontend framework ships no threads drawer -- React Native --, prove
+that thread with `npx --yes copilotkit@4.9.31 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. It either had
 one already or registered one before this step, so that finding is the answer and there is
@@ -237,6 +248,10 @@ The surface is a browser, and it also covers browser-origin CORS and CSP, which
 request never exercises. Drive it with the browser control step 6 named.
 
 1. Open the frontend URL from step 2 and wait for the page to finish loading.
+   Address it as `localhost` rather than an IP literal, for the reason step 3 gives
+   for the agent. A dev server reached on the IP literal can refuse its own static
+   assets, and a page that loads without them leaves the chat control dead. That
+   reads as a broken integration rather than as the host name you used.
 2. Take one page snapshot. Record whether the CopilotKit surface is on the page. A page
    that renders without it is a wiring failure rather than a proof to retry.
 3. Read the browser console before you type anything, and record every error already
@@ -317,6 +332,12 @@ result. The runtime must now report `licenseStatus`, and the authenticated Intel
 checks must pass. A thread for that request must be persisted and visible. Record both
 before and after evidence, and record that the criterion was `conversion-v1`.
 
+`licenseStatus` reports `unknown` while the runtime entitlement lookup for this project
+has not resolved yet. That value is transient rather than a failure, and the drawer
+renders its locked view for as long as it stands. Re-read `/info` and re-open the drawer
+before you judge either one. Criterion 4 requires `licenseStatus` to be present, and a
+present `unknown` meets it.
+
 For every other starting state, record Step 8 as not applicable.
 
 The application edit ban ends only after Step 8 passes or is recorded as not applicable.

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

@@ -6,6 +6,10 @@ Explain the exact step that failed. State whether authentication, project select
 credentials, the journey, a documentation URL, implementation, validation, or the round
 trip caused the route change. Do not say a path works when this release does not support it.
 
+If a protected path stopped this run, name that path and how it changed, in the words the
+audit printed. A report that says only that protected files changed cannot be acted on:
+nobody reading it can tell which file moved, or whether this run or the developer moved it.
+
 Stop onboarding without making more repository changes by default.
 
 The documentation-gap exception applies only before implementation starts. If implementation,
@@ -26,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 --yes copilotkit@4.9.17 onboard read fallback/best-effort`.
+`npx --yes copilotkit@4.9.31 onboard read fallback/best-effort`.
 
 Send one short report. Run the feedback command without another developer question. The
 CLI telemetry gate decides whether the report is sent.
 
 ```text
-npx --yes copilotkit@4.9.17 onboard feedback
+npx --yes copilotkit@4.9.31 onboard feedback
 ```
 
 Write the feedback message to the command's standard input, in at most four lines.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "copilotkit",
-  "version": "4.9.17",
+  "version": "4.9.31",
   "type": "module",
   "repository": {
     "type": "git",

package/release/release-tool.js

@@ -14698,7 +14698,7 @@ import * as path4 from "node:path";
 
 // apps/cli/src/config.ts
 function getTemplateRef() {
-  return true ? "f08f478cf73c46d34e8db03dedcc61f695f9b9b5" : "main";
+  return true ? "c2038cf52ced16dc814e2ff0bd60894f2a53f5c1" : "main";
 }
 
 // apps/cli/src/services/agentcore-config.ts
@@ -14881,6 +14881,20 @@ var TELEMETRY_ERROR_CODES = {
    * tell "the caller guessed a slug" from a malformed request.
    */
   PROJECT_NOT_FOUND: "PROJECT_NOT_FOUND",
+  /**
+   * `project select` persisted the record and the key-provisioning call did
+   * not succeed. Buckets as `network` because that is what it almost always
+   * is, and because the funnel needs half-applied selections visible next to
+   * the upstream failures that cause them (OSS-1089).
+   */
+  KEY_PROVISION_FAILED: "KEY_PROVISION_FAILED",
+  /**
+   * `project select` persisted the record and declined to write the key
+   * because git tracks the env file. Distinct from
+   * {@link TELEMETRY_ERROR_CODES.KEY_PROVISION_FAILED}: nothing upstream
+   * failed, and a retry alone will not clear it.
+   */
+  KEY_PROVISION_REFUSED: "KEY_PROVISION_REFUSED",
   CLI_PRODUCT_BINARY_TOO_LARGE: "CLI_PRODUCT_BINARY_TOO_LARGE",
   LEARNING_CONTAINER_ID_INVALID: "LEARNING_CONTAINER_ID_INVALID",
   LEARNING_PROJECT_ID_INVALID: "LEARNING_PROJECT_ID_INVALID",