copilotkit 4.10.1 → 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.
@@ -229,10 +274,13 @@ npx --yes copilotkit@latest onboard start \
 | `add-chat-suggestions`   | Configure and send visible chat suggestions                 |
 | `add-voice`              | Add documented voice transcription to the existing composer |
 | `add-realtime-sync`      | Prove managed thread changes sync between active clients    |
-| `add-channels`           | Connect Slack or Teams and prove a real mention             |
 
-Run `copilotkit channels setup` to copy `onboard start --intent add-channels` with a run id.
-`add-channels` does not need a CopilotKit web app. The graph asks Slack or Teams.
+Run `copilotkit channels setup` to copy the same small `onboard start --run <id>`
+prompt as the website CTA. There is no `--intent add-channels`. The copied
+prompt has no Channel sentence. When the project has no frontend, the root graph
+asks which frontend they want and offers Slack and Microsoft Teams there. If the
+copied prompt came from a Slack or Teams docs page, that page is the named
+frontend.
 Its first prompt records the coding agent with `onboard identify`, including when
 the entry command omitted `--coding-agent`. Channel setup stage events include
 the existing `onboarding_run_id` when the command runs inside an onboarding run;
@@ -250,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`
@@ -264,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:
@@ -276,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
@@ -370,8 +448,8 @@ copilotkit channels setup
 copilotkit channels setup --no-clipboard
 ```
 
-The command copies `onboard start --intent add-channels` with a run id.
-It installs the `channels-setup` skill, then prints a one-line prompt to paste
+The command copies the small `onboard start --run <id>` prompt.
+It installs the `channels-setup` skill, then prints that prompt to paste
 into your coding agent and copies it to your clipboard. The prompt is always
 printed, so you can read it before handing it over. Pass `--no-clipboard` in a
 headless or remote shell.
@@ -428,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.
@@ -453,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
@@ -460,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.
 
@@ -606,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.
 
@@ -707,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
 
@@ -929,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
@@ -1017,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.10.1"
+    "version": "4.12.0"
   },
   "intelligence": {
-    "commit": "b5b41dba88259cb723cfd2560be82b234417efa7"
+    "commit": "894cde3a9735b1605afef07a1250bef02a123ca4"
   },
   "copilotKit": {
-    "submittedInput": "7e6964f",
-    "commit": "7e6964fc11092b685bbea62bc331d5d177b738c1"
+    "submittedInput": "0048ba241fdf14a9036cdad11a4f31aa021a9c8d",
+    "commit": "0048ba241fdf14a9036cdad11a4f31aa021a9c8d"
   },
   "channel": "production",
-  "triggeringActor": "AlemTuzlak",
+  "triggeringActor": "BenTaylorDev",
   "workflow": {
-    "runId": "35080956003",
-    "runUrl": "https://github.com/CopilotKit/Intelligence/actions/runs/35080956003"
+    "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-16T09:44:44Z"
+  "builtAt": "2026-09-21T15:17:52Z"
 }