copilotkit 4.13.1 → 4.15.0

package/README.md

@@ -259,6 +259,48 @@ 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.
 
+### Signing in when the browser is on another machine
+
+The flow above sends the browser back to a loopback server on the CLI's own
+machine. That fails over SSH, in a VM, or in a container, because the browser
+runs somewhere else. From 4.14.0, the CLI uses a device authorization grant
+(RFC 8628) instead:
+
+```bash
+copilotkit login --device   # at a terminal
+copilotkit login --json     # for a coding agent
+```
+
+The CLI prints a page URL that carries an eight-character code, such as
+`WDJB-MJHT`, and prints the code too. Open the URL in a browser on any device
+and sign in if asked. The page opens on the confirmation screen: check that it
+shows the same code and where the request came from, then approve it. You can
+also open the plain page and type the code. The CLI polls until you approve,
+and gives up after 10 minutes.
+
+Under `--json`, the first `authentication_url` record is the URL with the code
+in it, and it also carries `user_code` and `expires_at`. A sign-in that ends without a session writes a `failed`
+record with `reason: expired` or `reason: access_denied`. If the Ops service
+has no device routes, `login --json` falls back to the loopback flow.
+
+Approve a code only if your own terminal or coding agent showed it to you. If
+someone sent you a code, deny the request: approving it signs their CLI in as
+you.
+
+## Where onboarding runs
+
+Run `onboard start` in the project folder, or in an empty folder for a new app.
+
+- In the home folder or a system folder, `onboard start` refuses, and no run
+  starts.
+- A folder that is not a project, but holds projects one or two levels down, is
+  a folder of projects. In one, `onboard start` lists the projects and tells the
+  coding agent to ask which one to use.
+- `init` never creates an app in the home folder, a system folder or a folder of
+  projects. It can create an app in a new subfolder of one, such as `~/my-app`.
+- A folder with its own Git repository is one project, even when its parts sit
+  in subfolders such as `frontend/` and `backend/`.
+
 ## Feature onboarding for existing apps
 
 Use the optional `--intent` flag when an existing CopilotKit app needs one
@@ -285,8 +327,8 @@ npx --yes copilotkit@latest onboard start \
 | `add-voice`              | Add documented voice transcription to the existing composer |
 | `add-realtime-sync`      | Prove managed thread changes sync between active clients    |
 
-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
+Run `copilotkit channels setup` to continue an unfinished Channels onboarding
+run, or copy the same onboarding URL prompt as the website CTA for a new run. 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
@@ -319,11 +361,13 @@ The developer can widen the scope the graph will not. The agent names one fix an
 asks. When the developer approves it, the agent makes that one fix and runs:
 
 ```bash
-npx --yes copilotkit@latest onboard resume
+npx --yes copilotkit@latest onboard resume --message "<the approved fix>"
 ```
 
-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
+The approval goes in `--message`, in one or two sentences and at most 500
+characters. The command also reads the approval from standard input when
+`--message` is absent. A piped approval puts its text in the command that a Codex
+approval covers, so the next call needs a new approval. 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
@@ -334,9 +378,14 @@ credential shape, and a run that never stopped each print a reason, serve nothin
 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.
+A feature run that broke reads `feature/stop` instead, and comes back the same
+way. That ending also covers a failed validation, a proof that could not be
+driven, and a missing Channel prerequisite, which one approved fix can answer.
+
+Only `stopped/run-failed` and `feature/stop` resume.
+`unsupported/no-validated-path` and `fallback/best-effort` describe a stack this
+release does not serve, and `feature/blocked-by-plan` is a refusal by the
+platform. No fix inside the run changes any of them.
 
 The onboarding commands are:
 
@@ -386,6 +435,10 @@ copilotkit init -n my-agent -f langgraph-py \
   slugs instead of creating something you did not ask for.
 - `-y`/`--yes` installs dependencies without asking; `--no-install` answers the
   same question without installing. `--install` is a longhand for `--yes`.
+- `--no-key-prompt` skips the question about a missing model key. Use it where the
+  shell is a pseudo-terminal but nobody types, such as a coding agent's shell:
+  there `init` sees a terminal and would ask anyway. The next steps still name
+  each missing key.
 
 A run with no terminal is refused only for what it has not answered, and every
 missing flag is named at once. Sign-in is the one answer no flag supplies:
@@ -398,6 +451,20 @@ already have a valid CLI session, the CLI reuses that workspace connection;
 otherwise it opens browser sign-in. This workspace connection is required for
 project creation and is separate from license issuance.
 
+## Import Mastra History
+
+Run `copilotkit import --source mastra --dry-run` to preview saved Mastra
+threads, then omit `--dry-run` to use the standard import confirmation and
+upload flow. Both a local persisted LibSQL database and a remote Mastra server
+are supported. Configure source identity and access with the
+[`MASTRA_IMPORT_*` variables](../../libs/import-mastra/README.md); destination
+Intelligence credentials use the usual import options.
+
+Local access requires Node 22.13+. Use the same source namespace when switching
+between local and remote access so repeat imports deduplicate. Import while the
+source is idle. This reads existing history and pending data; it does not execute
+models, tools or native resume operations.
+
 ## Managed Channels
 
 `copilotkit channels` connects a hosted Intelligence project to Slack or
@@ -443,6 +510,10 @@ 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`.
 
+If Microsoft sign-in fails, check the browser page for an `AADSTS` error code.
+The CLI shows a known code or `invalid_request` when Microsoft returns one in
+the terminal. It does not print the full Microsoft response.
+
 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.
@@ -458,7 +529,22 @@ copilotkit channels setup
 copilotkit channels setup --no-clipboard
 ```
 
-The command copies the small `onboard start --run <id>` prompt.
+If this project already has an unfinished Channels run, the command prints its
+existing ID and instructions to continue its route. It installs nothing, generates
+no ID, and leaves the clipboard unchanged. This includes paused runs and older
+bindings without timestamps; runs do not expire while waiting for you.
+
+Use `--run <id>` to name this project's unfinished run explicitly. Unknown,
+completed, or mismatched IDs are refused. Use `--new-run` instead to deliberately
+start another journey. The flags cannot be combined. A completed run or a run
+for another feature does not block a fresh Channels setup automatically.
+`copilotkit skills onboard --channels` honors the same run choices.
+If completion state cannot be saved, onboarding still completes and prints a
+warning. The next setup may require `--new-run` to start a fresh run.
+
+For a new run, the command copies an onboarding URL containing a fresh run ID.
+Before installing, it names the `channels-setup` skill, its
+`CopilotKit/CopilotKit/skills` source, and its project scope for all supported agents.
 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
@@ -500,6 +586,16 @@ those a project that never makes the call serves HTTP normally, reports no error
 and answers nothing. Mounts that own their process lifetime start on their own,
 and `status` distinguishes the two rather than warning about both.
 
+Managed API and realtime URLs have defaults; preflight needs the project API key,
+not an explicit WebSocket URL override. Runtime diagnostics refer to
+`CopilotRuntime`. Dynamic options and unresolved `channels` shorthand remain
+undetermined, while awaited optional chaining is recognized.
+
+If an onboarding run is already in progress, use `copilotkit onboard route` and
+`copilotkit onboard read <step>` to continue its current served step. Runtime
+wiring is covered by `feature/channels/implement`; paused runs must follow their
+stop instructions first. Outside a run, begin with `copilotkit channels setup`.
+
 `--json` emits a versioned envelope on stdout for agents and scripts, never
 prompts, and never opens a browser. See
 [Managed Channel CLI contracts](../../docs/channels-cli-contracts.md) for the
@@ -755,6 +851,14 @@ line on stdout so an already-issued token is not lost, and `project select` repo
 `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.
 
+## Onboarding credential baselines
+
+`copilotkit onboard protect --path .env` defers a credential file that does not
+exist yet. After the credential step creates it, run
+`copilotkit onboard protect --rebaseline --path .env` to protect its new contents.
+Later changes still fail the audit. The same rule applies to
+`.copilotkit/project.json`. Missing source files remain protected.
+
 ## Version Control
 
 Outside a repository, `copilotkit init` runs `git init` in the new app and makes
@@ -1023,7 +1127,7 @@ copilotkit logs --tail
 copilotkit logs --tail --lines 100
 ```
 
-With no flags, `copilotkit logs` prints the log file path. `--tail` prints recent structured log lines. Add `--verbose` to a CLI command when you need high-signal diagnostics mirrored to stderr during the run.
+With no flags, `copilotkit logs` prints the log file path. The log lives in `~/.copilotkit/cli.log` (or `$XDG_STATE_HOME/copilotkit/cli.log`). If a sandbox refuses writes there, the CLI logs to `$TMPDIR/copilotkit-<uid>/cli.log` instead, and if that also fails, the CLI runs with no log file. `--tail` prints recent structured log lines. Add `--verbose` to a CLI command when you need high-signal diagnostics mirrored to stderr during the run.
 
 Project creation (`init`/`create`) connects to and revalidates the live Clerk
 workspace before scaffolding. License commands, including `license list`,
@@ -1122,11 +1226,11 @@ again on the next interactive run.
 ## Preview and release builds
 
 Tester-facing prerelease builds are produced by CI via `workflow_dispatch` on
-the `pkg-pr-new (cli)` workflow — never built locally (the repo root `.env`
+the `CLI / Publish preview` workflow — never built locally (the repo root `.env`
 targets local services, and CI is the reproducible path).
 
 ```bash
-gh workflow run "pkg-pr-new (cli)" --ref <feature-branch> \
+gh workflow run publish-cli.yml --ref <feature-branch> \
   -f cli_env=production \
   -f template_ref=<copilotkit-branch-tag-or-commit>
 ```
@@ -1163,3 +1267,37 @@ and rollback are documented in the
 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).
+
+### Add existing threads to Learning
+
+Use `learning threads` to add prior conversations to a Container. A thread can
+join one Container permanently. Already-bound threads are ineligible.
+
+```bash
+copilotkit learning threads list support --binding all --json
+copilotkit learning threads list support --source slack --json
+copilotkit learning threads preview support --all --agent support-agent --from 2026-09-01 --to 2026-10-01 --json
+copilotkit learning threads commit support <operation-id> --yes --json
+copilotkit learning threads status support <operation-id> --json
+```
+
+Preview returns an operation ID, a frozen selection, and recovery counts. Use
+repeated `--thread <id>` flags instead of `--all` to select specific threads.
+Filters apply to thread creation time. `--from` is inclusive and `--to` is
+exclusive; date-only values use UTC. `list` accepts `--cursor` for the next page.
+The binding filter accepts `all`, `unbound`, `this_container`, or `other_container`.
+The source filter accepts `all`, `app`, `slack`, or `teams`, where `app` means the
+thread arrived straight from the Runtime and the provider values select threads a
+Channel created.
+
+Read the preview before commit. `--yes` approves permanent assignment of that
+saved selection. Each operation accepts at most 10,000 threads. New matching
+threads cannot enter an existing preview, and a repeated commit cannot bind a
+second batch. Threads bound by another action after preview are skipped and
+reported. Recovery continues in the background after the CLI exits.
+
+Results distinguish threads bound, runs harvested, runs unrecoverable, other
+skipped runs, and pending runs. Pending work is not a completed harvest. The
+preview reflects retained history at its timestamp; delayed events or retention
+changes can change the final result. `--json` prints a versioned result envelope
+on stdout, including errors, and failures exit nonzero.

package/cli-build-info.json

@@ -2,20 +2,20 @@
   "schemaVersion": 1,
   "package": {
     "name": "copilotkit",
-    "version": "4.13.1"
+    "version": "4.15.0"
   },
   "intelligence": {
-    "commit": "a629bd48ce4223ba2ea4fc1fb488973f8915807e"
+    "commit": "f6de0940e2aac5d2e323767f3d6431354715d2e6"
   },
   "copilotKit": {
-    "submittedInput": "f8047217b909a3e18404034f31f47157c4312241",
-    "commit": "f8047217b909a3e18404034f31f47157c4312241"
+    "submittedInput": "33db9a81ccfd",
+    "commit": "33db9a81ccfd2d6e820defe3c1616594909439af"
   },
   "channel": "production",
-  "triggeringActor": "BenTaylorDev",
+  "triggeringActor": "AlemTuzlak",
   "workflow": {
-    "runId": "35769780196",
-    "runUrl": "https://github.com/CopilotKit/Intelligence/actions/runs/35769780196"
+    "runId": "36016174452",
+    "runUrl": "https://github.com/CopilotKit/Intelligence/actions/runs/36016174452"
   },
   "validationResult": "passed",
   "ag2": {
@@ -24,5 +24,5 @@
     "revision": "main",
     "pinned": false
   },
-  "builtAt": "2026-09-22T18:52:16Z"
+  "builtAt": "2026-09-24T14:55:57Z"
 }