copilotkit 4.8.3 → 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
@@ -337,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:
@@ -377,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

package/cli-build-info.json

@@ -2,20 +2,20 @@
   "schemaVersion": 1,
   "package": {
     "name": "copilotkit",
-    "version": "4.8.3"
+    "version": "4.8.4"
   },
   "intelligence": {
-    "commit": "a000695b07fd11c83d6a82d51079f839a876be66"
+    "commit": "6483664ecea767ad39fe52106d85b94731740150"
   },
   "copilotKit": {
-    "submittedInput": "e0a2f00cca326c76739217e8ca40902e609539a4",
-    "commit": "e0a2f00cca326c76739217e8ca40902e609539a4"
+    "submittedInput": "47c5510b4909f6728288ecf28d7b14cd14922d33",
+    "commit": "47c5510b4909f6728288ecf28d7b14cd14922d33"
   },
   "channel": "production",
   "triggeringActor": "MikeRyanDev",
   "workflow": {
-    "runId": "32159069979",
-    "runUrl": "https://github.com/CopilotKit/Intelligence/actions/runs/32159069979"
+    "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-18T16:14:50Z"
+  "builtAt": "2026-08-25T03:52:56Z"
 }