copilotkit 4.8.2 → 4.8.4

package/README.md

@@ -36,6 +36,59 @@ its project-scoped `INTELLIGENCE_API_KEY`. Threads-enabled `init` and `create`
 scaffolds run the same hosted project selection and API-key provisioning path;
 use the built entrypoint when manually validating those steps too.
 
+### Selecting a project without a terminal
+
+The bare `project select` renders an interactive picker and therefore needs a
+TTY, which a coding agent's shell is not. `--project` and `--create` name the
+answer up front and run anywhere:
+
+```bash
+copilotkit project list --json                     # see the choices
+copilotkit project select --project <slug-or-id>   # pick an existing one
+copilotkit project select --create "My App" --json # create one and select it
+```
+
+`--project` and `--create` are mutually exclusive. `--project` is resolved
+against the organization's real projects, so a typo fails with the available
+slugs instead of recording a selection that points at nothing.
+
+`--json` emits one object on stdout:
+
+```json
+{
+  "type": "completed",
+  "project": { "id": "220", "slug": "my-app", "organizationId": "org_123" },
+  "config_path": "/work/my-repo/.copilotkit/project.json",
+  "api_key_provisioned": true
+}
+```
+
+`config_path` is absolute, and it is not always under the directory you ran in.
+The project record is repository-scoped: it goes into an existing `.copilotkit/`
+at or above the current directory when there is one, and otherwise into the
+repository root, so every part of a repository finds the same project. When that
+is not the current directory, `project select` says so on stderr. Read the path
+from this field rather than assuming `./.copilotkit/project.json`.
+
+The API key is not hoisted with it. It is written to the `.env` beside the
+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 `api_key_provisioned`, 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
+`INTELLIGENCE_API_KEY`, whose first run fails with an opaque "Failed to
+initialize thread". That field is the only machine-readable signal of it.
+Re-running `project select` is a valid recovery.
+
+Failures use the `login --json` shape, `{"error": "...", "type": "failed"}`, and
+exit 1.
+
+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
+piping stdout into a parser is safe.
+
 Do not run raw CLI source with commands such as
 `pnpm exec tsx apps/cli/src/index.ts login`; source execution bypasses the
 supported bundle, build-time defines, and packaging behavior, so it does not
@@ -60,6 +113,16 @@ commands. It stores the local CLI session used by `whoami`, `license`, and the
 `init`/`create` workspace connection; it does not scaffold a project or issue a
 license key by itself.
 
+For a coding agent that needs an agent-readable sign-in flow, use:
+
+```bash
+copilotkit login --json
+```
+
+The command prints JSON lines for the sign-in URL, the action to take, and the
+final result. It does not open a browser. A failed sign-in prints one final
+failure object and exits nonzero.
+
 The onboarding commands are:
 
 - `copilotkit init`
@@ -134,6 +197,12 @@ available. Where the flow needs you to do something in a provider console it
 stops and tells you what, why, which variables to set, and the exact command to
 resume with. A stop is a normal outcome and exits 0.
 
+At an interactive terminal, `channels add support --adapter teams` sets up the
+Microsoft app automatically when it finds no existing credential input. Existing
+Teams credentials in `.env` or the process environment keep the by-hand attach
+path. Pass `--no-provision` to choose that path yourself. Non-interactive runs
+stay on the by-hand path unless they pass `--provision`.
+
 No flag accepts a credential value. Credentials are read from your project's
 `.env`, from a named environment variable, or from a JSON document on stdin; at a
 terminal the CLI offers a masked prompt instead.
@@ -210,8 +279,20 @@ 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
 ```
 
+When the `learning.platform-v1` rollout flag is on, `copilotkit skills download`
+signs in through the existing CLI session, reads the project selected in the
+current directory, fetches that container's immutable ZIP through a
+project-scoped app-api route, checks its SHA-256 ETag when present, and extracts
+each skill directory into the new `--output` path.
+It stops if the output path already exists. A malformed archive, unsafe path,
+symbolic link, collision, or partial write leaves no output directory behind.
+The CLI rejects downloads over 20 MiB and bundles with more than 1,000 files,
+a file over 256 KiB, or more than 16 MiB of extracted content.
+
 `--channels` hands over the Slack Channel setup prompt instead of the generic
 add-CopilotKit-to-my-app prompt. It is the same prompt
 `copilotkit channels setup` prints; only the prompt differs, and the install
@@ -309,6 +390,22 @@ The Microsoft Agent Framework .NET template uses GitHub Models. Set its C# agent
 
 Do not commit generated `.env` files or personal secrets.
 
+## Version Control
+
+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.
+
+The project binding is recorded at that repository's root, so every directory in
+it resolves to the same project, and the run says where it went. If the root
+already binds a different project, the binding stays in the new app instead, so a
+repository holding two Intelligence apps keeps one for each.
+
 ## Run A Generated Project
 
 After scaffolding, the CLI prompts you to install dependencies:
@@ -349,6 +446,101 @@ For the Intelligence threads template, keep Docker Desktop running before `npm r
 
 ## Diagnostics
 
+Use `copilotkit verify` to check that a project's wiring works before debugging
+anything else:
+
+```bash
+copilotkit verify
+copilotkit verify --json                                    # machine-readable output
+copilotkit verify --runtime-url http://localhost:8080/copilotkit
+copilotkit verify --round-trip                              # also run the agent
+```
+
+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.
+
+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.
+
+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
+for it, so a runtime built without an Intelligence client runs in SSE mode and
+never reads the key — while still compiling, serving, and answering in a
+browser. `verify` reads the runtime's own reported license to tell the two
+apart, and only a running runtime can answer that, so the check stays `UNKNOWN`
+when the runtime is unreachable.
+
+Every check reports `PASS`, `FAIL`, or `UNKNOWN`, and `UNKNOWN` never means the
+check passed — an unreachable Intelligence API leaves the API key unproven
+rather than condemning it. `verify` exits non-zero unless every check passed, so
+a caller can branch on the command instead of parsing it. With `--json` the
+payload is the only thing on stdout and every diagnostic goes to stderr, so
+piping is safe.
+
+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.
+
+A runtime mounted `mode: "single-route"` refuses `GET /info`, so `verify` asks
+the same question again through the POST envelope that mount does answer.
+Reaching it that way counts as reachable, and the report says which shape
+answered. That mount carries no thread or memory route, though, so a licensed
+project on it fails the thread-route check with the mount named as the cause.
+Removing `mode: "single-route"` fixes it.
+
+### 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.
+
+```bash
+copilotkit verify --round-trip
+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.
+
+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
+records a thread, which is why it is opt-in rather than part of the bare command.
+
+`user-not-identified` is reported as `UNKNOWN` rather than `FAIL`. `identifyUser`
+is the project's own code and usually reads a signed-in session, which a CLI
+request does not carry, so an auth-gated app refusing it is that app working
+correctly. Pass what it reads with `--header`, repeatable.
+
+### What `verify` still does not prove
+
+It does not drive a browser. Realtime delivery to a browser over the gateway,
+browser-origin CORS and CSP, the frontend provider being wired to this runtime,
+and a generative UI component actually rendering are all invisible to a
+command-line check, and a round trip that passes here leaves every one of them
+unverified.
+
+It also cannot prove _which deployment_ answered. `--round-trip` proves that an
+executable agent stands behind the id this project declares — which `/info`
+alone cannot show, since it reports the names the runtime was configured with —
+but a runtime pointed at another project's agent answers under that same id, and
+a stale agent left running from earlier work still answers as though it were the
+new one.
+
 Use `copilotkit logs` when onboarding fails or support needs local CLI diagnostics:
 
 ```bash
@@ -365,12 +557,34 @@ revalidate the live Clerk organization before using local auth as needed. If a
 workspace or organization check fails because the cached session is stale, the
 CLI may clear local auth and rerun browser login before continuing.
 
+### A command, subcommand, or flag that should exist is rejected
+
+`npx` keys its cache on the spec string, so `copilotkit@latest` can keep serving
+a build it installed while `latest` was an older version. Input that ships in the
+published CLI then looks unshipped. Sandboxed environments with a prepopulated
+npm cache, and a global `copilotkit` earlier on `PATH`, produce the same symptom.
+
+Every rejection path — unknown command, unknown subcommand, and unknown option —
+names the version that actually ran. Read it before concluding something was
+never released, and compare it against the registry:
+
+```bash
+npm view copilotkit version          # what is published
+npx --yes copilotkit@<version> ...   # pin it explicitly; bypasses the cached spec
+rm -rf ~/.npm/_npx                   # if the pin is not enough
+```
+
+`copilotkit version` reports the same version alongside the build and commit.
+Adding `@latest` does not force a re-resolve; only an exact-version spec or a
+cache clear does.
+
 ## Telemetry
 
-The CLI collects anonymous usage data (command names, success/failure, timing —
-no project contents, no PII) to help improve the product. Collection is enabled
-by default; the first interactive run prints a one-time notice explaining what
-is collected and how to opt out.
+The CLI collects usage data such as command names, results, and timing. While
+you are signed in, the data is linked to your CopilotKit account. The onboarding
+feedback command can also send up to 2,048 UTF-8 bytes of text. Collection is
+enabled by default; the first interactive run prints a one-time notice that
+explains the data and how to opt out.
 
 Manage the preference at any time:
 

package/cli-build-info.json

@@ -2,20 +2,20 @@
   "schemaVersion": 1,
   "package": {
     "name": "copilotkit",
-    "version": "4.8.2"
+    "version": "4.8.4"
   },
   "intelligence": {
-    "commit": "fca6bc8954118609a6aa51d8635e632e72626706"
+    "commit": "6483664ecea767ad39fe52106d85b94731740150"
   },
   "copilotKit": {
-    "submittedInput": "53cf7e6575e8eae2a0dcaf64a7c3c2baf3e6dd04",
-    "commit": "53cf7e6575e8eae2a0dcaf64a7c3c2baf3e6dd04"
+    "submittedInput": "47c5510b4909f6728288ecf28d7b14cd14922d33",
+    "commit": "47c5510b4909f6728288ecf28d7b14cd14922d33"
   },
   "channel": "production",
   "triggeringActor": "MikeRyanDev",
   "workflow": {
-    "runId": "31119700532",
-    "runUrl": "https://github.com/CopilotKit/Intelligence/actions/runs/31119700532"
+    "runId": "32806721876",
+    "runUrl": "https://github.com/CopilotKit/Intelligence/actions/runs/32806721876"
   },
   "validationResult": "passed",
   "ag2": {
@@ -24,5 +24,5 @@
     "revision": "main",
     "pinned": false
   },
-  "builtAt": "2026-08-06T22:05:24Z"
+  "builtAt": "2026-08-25T03:52:56Z"
 }