copilotkit 4.11.0 → 4.12.0

package/LICENSE

@@ -0,0 +1,11 @@
+Copyright (c) Tawkit, Inc. All rights reserved.
+
+The CopilotKit CLI is proprietary software. No open-source license is granted
+for this package. Use is governed by your applicable signed agreement with
+Tawkit, Inc. or the CopilotKit Self-Service Agreement:
+https://www.copilotkit.ai/self-service-agreement
+
+Third-party components retain their own licenses. This notice does not change
+those licenses or the licenses of projects created with the CLI.
+
+Contact: legal@copilotkit.ai

package/README.md

@@ -19,6 +19,23 @@ CLI_ENV=local pnpm nx build cli
 node dist/apps/cli/index.js --help
 ```
 
+Everything above installs with no compiler on the machine.
+
+Microsoft Teams channel setup is the one exception. It runs
+`@microsoft/teams.cli`. That package depends on `keytar`, which builds a native
+keychain addon. So the CLI declares it as an **optional** dependency. A machine
+that cannot build it still installs and runs the CLI. Only Teams setup fails,
+and it reports the reason.
+
+To set up a Teams channel on such a machine, install the package yourself:
+
+```bash
+npm install @microsoft/teams.cli@3.0.3
+```
+
+That build needs a prebuilt binary, or `python3`, a C++ toolchain and the
+libsecret headers.
+
 ## Type-safe agent IDs
 
 `copilotkit typegen` reads a running CopilotKit runtime's `/info` route and
@@ -98,7 +115,11 @@ press Enter again to take it, or type a different one.
   "config_path": "/work/my-repo/.copilotkit/project.json",
   "project_file_written": true,
   "api_key_provisioned": true,
-  "environment_file_written": true
+  "environment_file_written": true,
+  "environment_file": {
+    "path": "/work/my-repo/web/.env",
+    "loadable_by_app": "pass"
+  }
 }
 ```
 
@@ -106,6 +127,15 @@ The four top-level summary fields let a coding agent read the result without
 searching the nested object or reading either file. The payload never contains
 the API key.
 
+`environment_file` answers the two questions `environment_file_written` cannot:
+which file the key went into, and whether an application will read it there.
+`loadable_by_app` is `pass` when the key sits in a directory an app loads env
+files from, `fail` when every such directory sits below it, and `undetermined`
+when no application package was found. On a `fail` it also carries `apps`, the
+directories that will not see the key. This command is the only step that can
+work that out, so a caller that ignores the field learns the same thing later
+from `copilotkit verify`.
+
 `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
@@ -119,9 +149,10 @@ repository with a `web/` and an `agent/` half, run `project select` in the half
 that needs the key.
 
 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
+select` names the directory that is expected to load the key, on stderr and in
+`environment_file`. Run from the root of a `web/` + `agent/` repository, the key
+lands at the root while the app in `web/` reads only `web/.env*`, the payload
+reports `"loadable_by_app": "fail"`, and `copilotkit verify` fails **The app can
 load the project API key** until it is written there instead.
 
 ### When only half of it lands
@@ -146,10 +177,19 @@ false, and a `retry_command`:
   "project_file_written": true,
   "api_key_provisioned": false,
   "environment_file_written": false,
+  "environment_file": {
+    "path": "/work/my-repo/web/.env",
+    "loadable_by_app": "pass"
+  },
   "retry_command": "copilotkit project select --project my-app"
 }
 ```
 
+`environment_file` is still reported here. `path` is the file the retry will write
+to rather than one this run wrote, and `loadable_by_app` describes that directory
+rather than a key that does not exist yet. Run the retry where `loadable_by_app`
+is `pass`, so it does not repeat the original mistake.
+
 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.
 
@@ -200,6 +240,11 @@ keep reading the same process until its terminal event. If the opener fails,
 show the URL for manual sign-in instead of retrying it. A failed sign-in prints
 one final failure object and exits nonzero.
 
+After the CLI exchanges the browser token and saves its credentials, the
+agent-onboarding callback page tries to close the tab. If the browser blocks
+closing, the page keeps a visible success message so the user can close it
+manually. Exchange or credential-save failures keep a visible error page open.
+
 The bundled onboarding prompt gives one short explanation before it opens the
 page: sign-in lets the coding agent create a project and API key, and the user
 can remove the key later to disconnect the workspace.
@@ -253,6 +298,36 @@ subagent returns, when the plan is approved, when implementation validation
 passes, and on each proof attempt and repair cycle. A run that cannot go on
 reads `feature/stop`, reports from there, and does not run `onboard complete`.
 
+### Coming back after a run that broke
+
+A run whose stack this release serves, and which broke anyway, reads
+`stopped/run-failed`. That node used to be the end of it. The graph refuses to
+widen its own scope, so a fix outside the approved plan had to happen outside the
+tracked run, and nothing after that point was recorded.
+
+The developer can widen the scope the graph will not. The agent names one fix and
+asks. When the developer approves it, the agent makes that one fix and runs:
+
+```bash
+npx --yes copilotkit@latest onboard resume
+```
+
+The approval goes to standard input, in one or two sentences and at most 500
+characters. The command puts the run back on the step that failed, keeps the same
+run id, and records both the approval and the step it re-entered. So the repair
+and the second proof attempt belong to the run that stopped, rather than to
+nothing at all. The approval is guarded and sent under the same telemetry setting
+as a friction report.
+
+A refused resume is not a failed step. A missing approval, an approval carrying a
+credential shape, and a run that never stopped each print a reason, serve nothing,
+and exit zero. A directory with no bound run is the one non-zero exit, and it is
+the refusal every other onboarding step makes there.
+
+Only `stopped/run-failed` resumes. `unsupported/no-validated-path` and
+`feature/stop` describe a stack this release does not serve, which no fix inside
+the run changes.
+
 The onboarding commands are:
 
 - `copilotkit init`
@@ -267,8 +342,8 @@ copilotkit create --name my-agent --framework langgraph-py
 
 Every supported framework ships with CopilotKit Intelligence (durable threads,
 persistence, insights). Managed `init` selects an Intelligence project and
-writes its project-scoped API key; it does not issue or write a managed license
-token. Local/self-hosted builds retain legacy license setup where required. The
+writes its project-scoped API key. It does not issue or write a license token.
+Local/self-hosted builds use a deployment license token when required. The
 `-i`/`--intelligence` flag is a deprecated no-op kept for compatibility.
 
 Rather than maintaining the list of framework values here, ask the CLI:
@@ -279,8 +354,8 @@ copilotkit framework list --json
 ```
 
 It reports every value `-f` accepts, the language each framework's agent is
-written in, and which init flags that framework supports — `-i`, `--mock`, and
-`--channel` are each accepted only for some. It answers from a catalog compiled into the
+written in, and which init flags that framework supports — `-i` and `--channel`
+are each accepted only for some. It answers from a catalog compiled into the
 binary, so it needs no API call, no authentication, and no TTY.
 
 ### Scaffolding without a terminal
@@ -431,6 +506,7 @@ copilotkit learning containers create
 copilotkit learning containers select
 copilotkit learning containers update support-quality
 copilotkit learning containers delete support-quality
+copilotkit learning containers default-id
 ```
 
 The create and update commands prompt for missing fields in a human terminal.
@@ -456,6 +532,7 @@ copilotkit learning containers create --id support-quality --name "Support quali
 copilotkit learning containers update support-quality --prompt-context "Use approved answers." --json
 copilotkit learning containers update support-quality --clear-prompt-context --json
 copilotkit learning containers delete support-quality --yes --json
+copilotkit learning containers default-id --json
 ```
 
 `--json` emits one versioned JSON object on stdout and never prompts. Create
@@ -463,6 +540,16 @@ requires `--id` and `--name`. Update requires at least one change flag. Delete
 requires `--yes`. Errors use the same JSON envelope and exit with a nonzero
 status.
 
+`default-id` prints the container id this project's slug derives to. One
+container per project is the default scope, so the id is a pure function of the
+slug the CLI already wrote into `.copilotkit/project.json`. It reads that record
+only: no credential, no network call, and no entitlement check. A slug that
+leaves nothing the id contract accepts reports `"status": "skipped"` with the
+reason `slug-unusable`, and a directory with no selected project reports
+`no-project-record`. Use it instead of deriving the id yourself. Two spellings
+of one project's id give it two containers, each below the 15 distinct
+conversations a first Learning run needs.
+
 A container keeps its stable ID. The list command returns at most 500 containers.
 If `nextCursor` is not null, pass it to `--cursor` to read the next page.
 
@@ -609,15 +696,15 @@ The CLI expects:
 Project creation requires a CopilotKit workspace connection through Ops/Clerk
 (browser sign-in when no session exists). Managed threads-framework templates
 use that connection to select a project and provision
-`CPK_INTELLIGENCE_API_KEY`; they do not request or write a license token.
-Local/self-hosted builds can still issue the legacy license where required.
+`CPK_INTELLIGENCE_API_KEY`. They do not request or write a license token.
+Local/self-hosted builds can still issue a deployment license token where required.
 
 ## Environment Files
 
 The scaffold step copies `.env.example` to `.env` when a template provides one.
 Managed scaffolds write `CPK_INTELLIGENCE_API_KEY` after project selection.
 Local/self-hosted scaffolds still ensure `COPILOTKIT_LICENSE_TOKEN` is present
-when the selected starter requires the legacy license.
+when the selected starter requires a deployment license.
 
 During scaffolding, `copilotkit init` interactively prompts for any required LLM vendor API key (`OPENAI_API_KEY` or `GOOGLE_API_KEY`) and writes it into `.env` for you — press Enter to skip and set it manually later.
 
@@ -710,7 +797,9 @@ python3 -m venv agents/.venv
 agents/.venv/bin/pip install -r agents/requirements.txt
 ```
 
-For the Intelligence threads template, keep Docker Desktop running before `npm run dev`. The root dev script starts the required Docker Compose services automatically when a license token is present in `.env` (without one it prints a "threads locked" hint and skips Docker), so a separate `docker compose up` step is only needed when you intentionally want to manage infrastructure by hand.
+Managed Intelligence scaffolds connect to hosted services with
+`CPK_INTELLIGENCE_API_KEY`. Their `npm run dev` command does not start a local
+Intelligence stack or require `COPILOTKIT_LICENSE_TOKEN`.
 
 ## Diagnostics
 
@@ -932,6 +1021,44 @@ 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 model call returns 401 after the credential was written
+
+A long-lived process reads its env file once, at launch. A credential written
+into that file afterwards is correct on disk and absent from the process, so
+every model call fails and the stack trace points at the agent framework rather
+than at the key.
+
+Ask which running processes predate the file they read:
+
+```bash
+copilotkit onboard env-staleness
+copilotkit onboard env-staleness --json
+```
+
+It reports one line per listening process inside the project: `stale` names the
+env file and how long after launch it was written, `current` means no file it
+reads changed since it started, and `unknown` names why it could not be placed.
+A probe that could not run reports that too, because an empty list otherwise
+reads as "nothing is stale" and rules out the cause.
+
+It reads only. No credential, no network call, and no bound run. It reports the
+first token of the executable name as `ps` reports it, never the arguments, and
+never a value from an env file.
+
+Candidates are listening TCP sockets, owned by you, whose working directory is
+inside the project. Everything else is counted on one line and never examined, so
+the answer is not buried under your containers and editors. That bounds what the
+reading can see, and an empty result is not a clean bill of health: a server in a
+container, behind a unix socket, or run by another user does not appear, and a
+container exposes its port through the container runtime rather than from a
+directory inside the project. The command says so rather than reporting that
+nothing is stale.
+
+It recommends stopping nothing. The CLI cannot prove which processes a run
+started, and a starter that serves both halves from one script loses both when
+either one goes down. Restart what you started, with the command you started it
+with, and leave the rest running.
+
 ### A command, subcommand, or flag that should exist is rejected
 
 `npx` keys its cache on the spec string, so `copilotkit@latest` can keep serving
@@ -1020,3 +1147,9 @@ first.
 Production validation, publication, provenance inspection, post-npm recovery,
 and rollback are documented in the
 [CLI release runbook](../../docs/runbooks/cli-release.md).
+
+## Package license
+
+The CLI is commercial software. Its npm manifest uses `SEE LICENSE IN LICENSE` and includes
+a [commercial notice](LICENSE). This notice does not change the licenses of
+projects created with the CLI. See the [package license map](../../docs/licensing/package-licenses.md).

package/cli-build-info.json

@@ -2,20 +2,20 @@
   "schemaVersion": 1,
   "package": {
     "name": "copilotkit",
-    "version": "4.11.0"
+    "version": "4.12.0"
   },
   "intelligence": {
-    "commit": "362d341410722307c1067c71ac14710245300cff"
+    "commit": "894cde3a9735b1605afef07a1250bef02a123ca4"
   },
   "copilotKit": {
-    "submittedInput": "dc1238c0bd473e259c992b85026cb30fe6b3b726",
-    "commit": "dc1238c0bd473e259c992b85026cb30fe6b3b726"
+    "submittedInput": "0048ba241fdf14a9036cdad11a4f31aa021a9c8d",
+    "commit": "0048ba241fdf14a9036cdad11a4f31aa021a9c8d"
   },
   "channel": "production",
-  "triggeringActor": "tylerslaton",
+  "triggeringActor": "BenTaylorDev",
   "workflow": {
-    "runId": "35162202498",
-    "runUrl": "https://github.com/CopilotKit/Intelligence/actions/runs/35162202498"
+    "runId": "35617651318",
+    "runUrl": "https://github.com/CopilotKit/Intelligence/actions/runs/35617651318"
   },
   "validationResult": "passed",
   "ag2": {
@@ -24,5 +24,5 @@
     "revision": "main",
     "pinned": false
   },
-  "builtAt": "2026-09-16T23:26:51Z"
+  "builtAt": "2026-09-21T15:17:52Z"
 }