copilotkit 4.9.17 → 4.9.31

package/README.md

@@ -19,6 +19,25 @@ CLI_ENV=local pnpm nx build cli
 node dist/apps/cli/index.js --help
 ```
 
+## Type-safe agent IDs
+
+`copilotkit typegen` reads a running CopilotKit runtime's `/info` route and
+writes `.copilotkit/types.ts` plus `.copilotkit/register.d.ts`. After
+TypeScript includes `register.d.ts`, `agentId` on `@copilotkit/react-core/v2`
+is the union of the agents that runtime declared.
+
+```bash
+npx copilotkit typegen
+npx copilotkit typegen http://localhost:3000/api/copilotkit
+```
+
+The default URL matches `copilotkit verify`. Generated files sit next to
+`.copilotkit/project.json`. The command ignores those two files only. It does
+not ignore the whole `.copilotkit/` directory.
+
+If `tsconfig.json` is JSONC, add `".copilotkit/register.d.ts"` to `include` by
+hand.
+
 ## Manual local validation
 
 For manual login/session and hosted-project validation, run the supported built
@@ -83,16 +102,44 @@ directory you ran in, because that is the file the app process loads — so in a
 repository with a `web/` and an `agent/` half, run `project select` in the half
 that needs the key.
 
-**Check all four summary fields, not just the exit code.** Key provisioning is
-deliberately non-fatal: if it fails, the selection is still persisted, a warning
-goes to stderr, and the command still exits 0 — leaving a scaffold with no
-`CPK_INTELLIGENCE_API_KEY`, whose first run fails with an opaque "Failed to
-initialize thread". `api_key_provisioned` and `environment_file_written` are
-false in this state.
-Re-running `project select` is a valid recovery.
+When the directory you ran in is not itself a CopilotKit package, `project
+select` names the directory that is expected to load the key on stderr. Run from
+the root of a `web/` + `agent/` repository, the key lands at the root while the
+app in `web/` reads only `web/.env*`, and `copilotkit verify` fails **The app can
+load the project API key** until it is written there instead.
+
+### When only half of it lands
+
+Key provisioning does not throw away a selection it could not finish. If minting
+the key fails, the project record is still written and the scaffold has no
+`CPK_INTELLIGENCE_API_KEY` — whose first run fails with an opaque "Failed to
+initialize thread".
+
+That state has an exit status of its own. `project select` exits **75**
+(`EX_TEMPFAIL`: partially applied, retry is safe), prints what was written and
+what was not, and names the retry. With `--json` the payload is still emitted,
+with `"type": "partial"`, `api_key_provisioned` and `environment_file_written`
+false, and a `retry_command`:
+
+```json
+{
+  "type": "partial",
+  "selected_project_slug": "my-app",
+  "project": { "id": "220", "slug": "my-app", "organizationId": "org_123" },
+  "config_path": "/work/my-repo/.copilotkit/project.json",
+  "project_file_written": true,
+  "api_key_provisioned": false,
+  "environment_file_written": false,
+  "retry_command": "copilotkit project select --project my-app"
+}
+```
+
+Keep the record and re-run the command it names. A retry converges on the same
+state as a first-time success: the same project, the same binding, plus the key.
 
-Failures use the `login --json` shape, `{"error": "...", "type": "failed"}`, and
-exit 1.
+Exit statuses: **0** everything landed, **75** the record was written and the key
+was not, **1** nothing was applied. Failures use the `login --json` shape,
+`{"error": "...", "type": "failed"}`.
 
 With `--json` the payload is the only thing on stdout — warnings, errors, and
 (when no selector is passed) the interactive picker all go to stderr — so
@@ -306,13 +353,17 @@ Use `copilotkit create` to start a **new** project. Use `copilotkit skills onboa
 when you already have an app and want your coding agent to add CopilotKit for you.
 
 ```bash
+# Default: install in this project, sign in, and get the agent prompt.
+copilotkit skills onboard
+copilotkit skills onboard --no-clipboard
+copilotkit skills onboard --channels
+
+# Custom: show the installer so you can inspect or change its choices.
 copilotkit skills install
 copilotkit skills install -y
 copilotkit skills install --skill react-core,runtime --agent claude-code
 copilotkit skills install --list
-copilotkit skills onboard
-copilotkit skills onboard --no-clipboard
-copilotkit skills onboard --channels
+
 # Run `copilotkit project select` in this directory first.
 copilotkit skills download <learning-container-id> --output ./learned-skills
 ```
@@ -332,42 +383,41 @@ add-CopilotKit-to-my-app prompt. It is the same prompt
 `copilotkit channels setup` prints; only the prompt differs, and the install
 and sign-in are unchanged.
 
-`copilotkit skills install` installs CopilotKit agent skills for your coding
-agent (Claude Code, Codex, Cursor, Gemini, and others) by running the standalone
-`skills` installer under the hood.
+`copilotkit skills onboard` installs every CopilotKit skill in the current
+project without showing the installer's picker. It writes the shared
+`.agents/skills` path used by Codex, Cursor, Gemini CLI, and other compatible
+agents, plus `.claude/skills` for Claude Code. The command shows one progress
+line, then prints a short install receipt.
+
+It then:
+
+- signs you in with your CopilotKit account, reusing an existing session;
+- stops before it changes the app itself;
+- copies a ready-to-paste agent prompt, or prints it when no clipboard works.
 
-By default it installs every skill and prompts you to choose which coding agents
-to install them to. Narrow or automate the install with these flags (they work
-on both `install` and `onboard`):
+Pass `--no-clipboard` to always print the prompt. `onboard` needs an interactive
+terminal because it may open a browser for sign-in.
+
+Use `copilotkit skills install` when you want to see or change the agent
+selection. It shows the standalone installer's picker and output, then stops
+before sign-in. CopilotKit keeps that output visible, exits nonzero when any
+target fails, and does not print a false success receipt. These flags work on
+both commands unless noted:
 
 - `-s, --skill <names>` — comma-separated skills to install (default: all),
   e.g. `--skill react-core,runtime`.
 - `-a, --agent <names>` — comma-separated coding agents to install to
-  (default: choose interactively), e.g. `--agent claude-code,cursor`.
-- `-y, --yes` — install everything (all skills to all agents) non-interactively.
+  (`onboard` uses the shared and Claude Code paths; `install` asks), e.g.
+  `--agent claude-code,windsurf`.
+- `-y, --yes` — skip prompts; omitted skill or agent selections default to all.
 - `--global` — install at the user level instead of the current project.
 - `--list` — list the available skills and exit without installing (`install`
   only).
 
-Choosing which coding agents to install to is interactive, so a non-interactive
-environment (CI, scripts) must make the choice deterministic: pass `-y` to
-install everything, or `--agent <name>` to target specific agents. Otherwise the
-command exits with guidance instead of hanging.
-
-`copilotkit skills onboard` is a superset of `install`. It also:
-
-- signs you in with your CopilotKit account, reusing your existing session and
-  opening a browser sign-in only when you are not already signed in;
-- stops before any repo-specific file changes — your coding agent performs the
-  actual integration using the installed skills;
-- copies a ready-to-paste agent prompt to your clipboard, and prints it instead
-  when the clipboard is unavailable.
-
-Pass `--no-clipboard` to always print the prompt instead of copying it. This is
-useful in headless or remote shells where clipboard access is unavailable.
-`onboard` requires an interactive terminal because it opens a browser to sign
-in; use `skills install -y` (or `--agent <name>`) for non-interactive
-environments.
+In CI or a script, run `skills install -y` to target every supported agent, or
+pass `--agent <name>` for exact project-local targets. Add `--global` only for a
+user-level install. Bare `skills install` exits with a clear message when it
+cannot show the picker.
 
 When to use which:
 
@@ -424,6 +474,19 @@ The Microsoft Agent Framework .NET template uses GitHub Models. Set its C# agent
 
 Do not commit generated `.env` files or personal secrets.
 
+Before writing a credential, `copilotkit license --write` and
+`copilotkit project select` ask git whether it ignores the target `.env`. When it
+does not, they append `.env`, `.env.*` and `!.env.example` to your `.gitignore` as
+one marked block, leaving your existing lines untouched. A `.gitignore` listing
+only `.env` does not cover `.env.local`, so a credential written beside it is
+staged by the next `git add -A`.
+
+Appending a pattern cannot untrack a file git already tracks. In that one case
+neither command writes the credential: `license` prints the `COPILOTKIT_LICENSE_TOKEN`
+line on stdout so an already-issued token is not lost, and `project select` reports
+`api_key_provisioned: false` and exits 75. Untrack the file, then re-run. Outside a
+git work tree there is nothing to protect and both write as before.
+
 ## Version Control
 
 Outside a repository, `copilotkit init` runs `git init` in the new app and makes
@@ -491,19 +554,30 @@ copilotkit verify --round-trip                              # also run the agent
 copilotkit verify --expect-runtime oss --round-trip --agent incident_triage
 ```
 
-It checks that a hosted project is selected, that a project API key is present
-and authenticates against Intelligence, that the CopilotKit runtime responds,
-that the runtime declares at least one agent, that the runtime is actually
-using the credential, and that it serves the thread routes the license pays
-for. It also reports the runtime version, the agent framework in use, the
-realtime gateway wiring, the plan, and the license state.
+It checks that a hosted project is selected, that a project API key is present,
+that the app's own process can load that key, that the key authenticates
+against Intelligence, that the CopilotKit runtime responds, that the runtime
+declares at least one agent, that the runtime is actually using the credential,
+and that it serves the thread routes the license pays for. It also reports the
+runtime version, the agent framework in use, the realtime gateway wiring, the
+plan, and the license state.
 
 The selected project is read from the nearest `.copilotkit/project.json` at or
 above the current directory, stopping at the repository root, so running from
 one half of a repository finds the project the repository is bound to. `verify`
 names the directory it read the project from, and names where it searched when
-it found none. The API key is read from the `.env` beside the current directory
-only, because that is the file the app process loads.
+it found none. The API key is searched for the same way: `.env` and `.env.local`
+from the current directory up to the repository root.
+
+Being found is not the same as being loadable. A framework's env loader does not
+walk up — Next.js, Vite, Nuxt and Astro all read env files from the application's
+own directory — so a key at the repository root is invisible to an app in a
+subdirectory. `verify` reports the two facts separately: **A project API key is
+present** says the credential exists somewhere in this repository, and **The app
+can load the project API key** says the directory the app runs in supplies it.
+The second is `UNKNOWN` rather than `FAIL` wherever it cannot decide: no package
+declaring a `@copilotkit/*` dependency was found, more than one was, or a script
+in the app names an env file itself with `dotenv`, `env-cmd`, or `--env-file`.
 
 That last check is the one a passing build cannot give you. A key in `.env`
 proves only that one was provisioned: the runtime reads no environment variable
@@ -526,10 +600,37 @@ exits zero only when `/info` is valid, declares the agent named by `--agent`,
 omits `licenseStatus`, and `--round-trip` passes. Both `--round-trip` and
 `--agent` are required for an OSS pass.
 
-The runtime URL defaults to `http://localhost:3000/api/copilotkit` and the
-report always states which URL it probed, because a wrong default is the most
-likely reason for a runtime failure. Pass `--runtime-url` when the frontend
-serves the runtime elsewhere.
+### Which runtime URL gets probed
+
+`verify` works the port out from the project rather than assuming one. In order:
+
+1. `--runtime-url`, when you pass it.
+2. `"runtimeUrl"` in `.copilotkit/project.json` — an absolute URL you add by
+   hand for a project whose runtime is somewhere none of the below can find it.
+   The CLI never writes this field and never removes one you wrote.
+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,
+   or a `-p` / `--port` flag on its `dev` script, including a script that `dev`
+   delegates to through `concurrently`. Only a web dev server's port counts, so
+   the agent half's port is never mistaken for the frontend's.
+5. `http://localhost:3000/api/copilotkit`, assumed.
+
+The app directory is the CopilotKit package you are in, or — running from the
+repository root of a two-half project — the one package below you that depends
+on CopilotKit. More than one, and `verify` names them instead of choosing.
+
+The report always states the URL it probed **and where that URL came from**,
+because those two facts mean opposite things when nothing answers. Silence at a
+URL the project named is a `FAIL`. Silence at the assumed default is `UNKNOWN`,
+with the two ways to tell the command where to look — a working application on
+another port is not a wiring failure, and reporting it as one is how a developer
+ends up undoing correct work.
+
+The mount path is not discovered: every first-party starter serves the runtime
+at `/api/copilotkit`, and reading a framework's routing conventions to find out
+otherwise is the kind of check that drifts and starts reporting confident
+nonsense. Where yours is elsewhere, use option 1 or 2.
 
 A runtime mounted `mode: "single-route"` refuses `GET /info`, so `verify` asks
 the same question again through the POST envelope that mount does answer.

package/cli-build-info.json

@@ -2,20 +2,20 @@
   "schemaVersion": 1,
   "package": {
     "name": "copilotkit",
-    "version": "4.9.17"
+    "version": "4.9.31"
   },
   "intelligence": {
-    "commit": "2e15855e40f342daf1805da34a8ac3d9e708e082"
+    "commit": "5f88d6f4e26b643eb1223b12cc05dad94055b5ef"
   },
   "copilotKit": {
-    "submittedInput": "f08f478cf73c46d34e8db03dedcc61f695f9b9b5",
-    "commit": "f08f478cf73c46d34e8db03dedcc61f695f9b9b5"
+    "submittedInput": "c2038cf52ced16dc814e2ff0bd60894f2a53f5c1",
+    "commit": "c2038cf52ced16dc814e2ff0bd60894f2a53f5c1"
   },
   "channel": "production",
-  "triggeringActor": "maxkorp",
+  "triggeringActor": "BenTaylorDev",
   "workflow": {
-    "runId": "33436603154",
-    "runUrl": "https://github.com/CopilotKit/Intelligence/actions/runs/33436603154"
+    "runId": "33679806270",
+    "runUrl": "https://github.com/CopilotKit/Intelligence/actions/runs/33679806270"
   },
   "validationResult": "passed",
   "ag2": {
@@ -24,5 +24,5 @@
     "revision": "main",
     "pinned": false
   },
-  "builtAt": "2026-08-31T20:34:20Z"
+  "builtAt": "2026-09-02T20:33:23Z"
 }