copilotkit 4.23.1 → 4.25.0

package/README.md

@@ -283,15 +283,22 @@ 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.
+also open the plain page and type the code. A code lasts 10 minutes. If
+nobody approves it in time, the CLI prints a new code and keeps polling. It
+does this twice, so it gives up after about 30 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`
+in it, and it also carries `user_code` and `expires_at`. A renewed code writes
+another `authentication_url` record, with `renewed: true` and its `renewal`
+number, and another `action_required` record. The old page then shows an
+expired code, so show the developer the new one. A sign-in that ends without a session writes a `failed`
 record with `reason: expired` or `reason: access_denied`, and with
-`retry: ask_developer`: a person must act before a new code can work. After 2
-codes in a row expire with nobody approving them, `login --json` refuses to
-request another. It writes a `failed` record with `reason: repeated_expiry` and
+`retry: ask_developer`: a person must act before a new code can work. If a
+code expired and the request for its replacement failed, for example on a rate
+limit, the record says `reason: renewal_failed` and its `error` names that
+failure. After 2
+sign-ins in a row end with nobody approving any of their codes, `login --json`
+refuses to request another. It writes a `failed` record with `reason: repeated_expiry` and
 exits non-zero. Run `copilotkit login --json --force` when someone is ready to
 approve. Any sign-in that succeeds resets the count, and the count lapses after
 a day.
@@ -321,12 +328,43 @@ folder and paste the prompt that they copied. It also gives a line to paste
 that continues the same run. An agent that the CLI does not detect reads the
 full prompt above the note, so the note does not block it.
 
+### Where a run keeps its state
+
+The run keeps its state in `.copilotkit/onboarding/` in the folder where
+`onboard start` ran. The state is the run id, the route, the proof results and
+the coding agent. The folder holds a `.gitignore` that contains `*`, so git
+never lists it. Delete the folder to forget the run.
+
+If the project folder cannot be written, the CLI keeps the state in its config
+store in your home folder instead. A run started by an earlier CLI version is
+read from there too.
+
+The sign-in, the telemetry install id and the protected-path baseline stay in
+the config store in your home folder. A rebuilt devcontainer gets a fresh home
+folder, so it keeps the run but loses the sign-in and counts as a new install.
+To keep them, set `COPILOTKIT_CONFIG_DIR` to an absolute path on a mounted
+volume, in the devcontainer configuration or your shell profile:
+
+```json
+{
+  "containerEnv": { "COPILOTKIT_CONFIG_DIR": "/workspaces/.copilotkit-home" }
+}
+```
+
+The CLI then keeps its stores in `auth/` and `config/` under that folder, and
+its log in `logs/`. On Linux, `XDG_CONFIG_HOME` also moves the stores.
+
+Do not point `COPILOTKIT_CONFIG_DIR` inside the project. The sign-in token
+would sit where a coding agent can read it or commit it.
+
 ## Feature onboarding for existing apps
 
 Use the optional `--intent` flag when an existing CopilotKit app needs one
 specific feature. The CLI prints a feature-specific Markdown path; the coding
 agent follows its inspection, plan, implementation, and visible-proof steps.
 Without `--intent`, `onboard start` keeps the generic onboarding path unchanged.
+Each feature path starts with `onboard identify`, as the generic path does, because
+the environment can detect only some coding agents.
 
 ```bash
 npx --yes copilotkit@latest onboard start \
@@ -356,19 +394,69 @@ frontend.
 Its first prompt records the coding agent with `onboard identify`, including when
 the entry command omitted `--coding-agent`. The agent also passes `--model` with
 the exact model id its instructions name, and leaves it out when they name none.
-It passes `--model-family` with its model family, such as `gpt-5`, for the agent
-that cannot see its exact id. The event records a missing id or family as
-`unknown`, and a value that is not a model, such as a coding-agent product name,
-as `unreportable`. It records the coding agent the environment shows as
+It always passes `--model-family`, picked from a fixed list such as `claude-opus`
+or `gpt-5`. The event reports `coding_agent` and `model_family` normalized to
+fixed lists, so `copilot` and `github-copilot-cli` both read `github-copilot`,
+and keeps what the agent wrote in `coding_agent_raw` and `model_family_raw`. A
+missing family is read from the model id when it names one. The event records a
+missing id or family as `unknown`, a value that is not a model, such as a
+coding-agent product name, as `unreportable`, and a name not on the list as
+`other`. It records the coding agent the environment shows as
 `detected_coding_agent`, and sets `coding_agent_mismatch` when that agent differs
-from the declared one. `cli.onboarding.started` also carries
+from the declared one. The CLI reads the agent from environment variables the
+agent sets. When only markers that leak into child agents are set (`AI_AGENT`,
+`CLAUDECODE`), or several agents' markers are, the nearest parent process that
+is an agent's binary decides. With no marker, it reads the parent processes.
+Set `COPILOTKIT_SKIP_AGENT_PROCESS_PROBE=1` to skip the parent-process walk. It
+sends only the matched agent name, never a path or a command line, and records
+where it found it in `detected_coding_agent_source`. `cli.onboarding.started` also carries
 `detected_coding_agent`, because a run that stops before `onboard identify` sends
 no identify event. It also carries `audience`: `detected-agent` when the
 environment shows an agent, `human-terminal` for a terminal with no detected
-agent, and `non-tty` otherwise. Channel setup stage events include
+agent, and `non-tty` otherwise. Before sign-in, the first prompt records where the
+app stores data with `onboard deployment --choice <managed|local>`. The
+`cli.onboarding.deployment_chosen` event carries that `deployment` and
+`local_offered`, which this CLI release reads from its local evaluation flag.
+No run is asked to choose, so `local_offered: true` means only that this release
+can run local. A developer who asks for local after the first prompt recorded
+managed sends a second event with `local`, so the last event in a run is its
+choice. Channel setup stage events include
 the existing `onboarding_run_id` when the command runs inside an onboarding run;
 standalone commands omit it. These events use the CLI's existing telemetry consent gate.
 
+Local setup reports how long each phase took, while it runs. During `init --local`,
+`local setup`, or `local update`, the CLI sends these events:
+
+- `cli.local.setup_phase_started` when a phase begins.
+- `cli.local.setup_phase_completed` when the phase ends.
+- `cli.local.setup_completed` once, for the whole setup.
+
+The fields:
+
+- A phase event carries `setup_phase`, a fixed slug such as `images-download` or
+  `services-start`, and `phase_visit`. The installer returns to some phases, so each
+  visit sends its own event with only that visit's `duration_ms`. Add the visits to get
+  the phase's time for one setup.
+- A finished phase event carries `duration_ms` and `outcome`. The image download phase
+  adds `bytes_downloaded` and `image_count`.
+- `release` is present only after setup knows the installed release, so early phase
+  events do not have it. The total always has it when setup finished.
+- The total carries `duration_ms`, `outcome`, and `phase_count`. A failed setup adds
+  `failed_setup_phase`.
+- On Ctrl-C or SIGTERM, the open phase and the total send `outcome: abandoned` before
+  the CLI exits. The total adds `abandoned_setup_phase` and the `bytes_downloaded` so
+  far. The CLI waits at most 2 seconds for these sends, then exits with the signal's
+  usual status.
+- Every event carries `onboarding_run_id` when the app belongs to an onboarding run.
+  For `init --dir <target>`, the CLI reads the run from the current directory first,
+  then from the target directory.
+
+The events carry no path, label text, or credential.
+
+Outside a terminal, for example in a coding agent's shell, a long phase prints one
+progress line at most every 15 seconds, such as
+`Downloading container images… 4 of 11 · 1.2 GB`. With `--json`, nothing extra is printed.
+
 The intent describes the developer's requested outcome, not a claim about the
 current project state. Each path inspects the app first: it preserves a proven
 existing configuration, stops rather than inventing credentials or identities,
@@ -950,8 +1038,8 @@ Inside a git repository, the first `onboard protect` records the files that git
 lists as changed or untracked. Git can restore committed files, so the baseline
 leaves them out. Outside a repository, the baseline records every file under the
 run's folder, except in `node_modules`, `dist`, `build`, `out`, `coverage`,
-`.next`, `venv` and `__pycache__`. The capture report says which of the two it
-used.
+`.next`, `venv`, `__pycache__` and the run's own state in
+`.copilotkit/onboarding/`. The capture report says which of the two it used.
 
 A git repository at your home directory, or above it, does not count as the
 repository of a project below it. It is usually a dotfiles or accidental
@@ -1256,6 +1344,31 @@ correctly. Pass what it reads with `--header`, repeatable. `verify` sends
 the header on every request to the runtime, `/info` included, so a runtime
 behind auth needs no local proxy.
 
+### Proving a thread the app created
+
+Some apps refuse a run that `verify` starts: an `identifyUser` that reads a
+signed-in session, or an app that runs only threads it created. For those, send
+one message in the app and pass that thread's id with `--thread`:
+
+```bash
+copilotkit verify --thread <thread-id>
+copilotkit verify --thread <thread-id> --expect-learning-container support-desk
+copilotkit onboard proof-check --thread <thread-id> --json
+```
+
+`--thread` replaces `--round-trip`. It starts no agent run and asks the app for
+no thread. It reads the thread from app-api with the project key, so it needs no session, and
+`--expect-learning-container` checks that same thread. A pass proves that the
+agent's answer was recorded on that thread. It does not prove which end user the
+thread belongs to. A thread app-api does not hold for this project is a `FAIL`.
+Only an answer after the thread's newest user message counts. Inside an
+onboarding run, a thread that did not change after the run started is a `FAIL`,
+because its answer can predate the app as it is now. With `--agent`, a thread
+of another agent is a `FAIL`, and the evidence names the thread's own agent.
+Telemetry marks a proof made this way with `proof_source: app-thread`.
+The page-context check needs a run of its own, so with `--thread` it is a
+warning that names the browser as the place to prove it.
+
 ### What `verify` still does not prove
 
 It does not drive a browser. Realtime delivery to a browser over the gateway,
@@ -1279,7 +1392,7 @@ copilotkit logs --tail
 copilotkit logs --tail --lines 100
 ```
 
-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.
+With no flags, `copilotkit logs` prints the log file path. The log lives in `~/.copilotkit/cli.log` (or `$XDG_STATE_HOME/copilotkit/cli.log`, or `$COPILOTKIT_CONFIG_DIR/logs/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`,
@@ -1370,10 +1483,16 @@ The command reads the key from the env file (`.env` by default) and sends one
 request with a one-token answer to that vendor. The call costs a fraction of a
 cent. It knows `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, and `GOOGLE_API_KEY`.
 
+When the env file has no real value for the key, the command checks the value
+in the environment instead. A key you export in the shell, or set with direnv or
+`op run`, reaches the dev server the same way. `source` in the JSON says where
+the value came from: `env-file` or `environment`.
+
 - `pass`: the vendor served a model call with the key.
 - `fail`: the vendor refused the key. The cause is `model_quota` (no credits) or
   `model_auth` (a rejected key).
-- `missing`: the env file or the key is absent, or the value is a placeholder.
+- `missing`: neither the env file nor the environment holds a real value for
+  the key.
 - `unsupported` or `undetermined`: the check did not settle it. A rate limit, a
   vendor outage, or a probe model the key may not use proves nothing about the
   key, so none of them is a `fail`.
@@ -1383,6 +1502,10 @@ SDK at another endpoint, or when the shell exports a different value for the
 key. It never prints the key, and it never prints the vendor's error message,
 because a vendor can echo part of the key in it.
 
+During an onboarding run, a `pass` also replaces a `missing` or `fail` that the
+credentials step kept for the same key in the same env file. So after the
+developer fixes the key, `onboard proof-check` runs the round trip again.
+
 ### An onboarding run stops while it selects the project
 
 The onboarding graph settles the project, its key, and the Learning Container
@@ -1430,11 +1553,29 @@ copilotkit onboard credentials --model-key OPENAI_API_KEY \
 The step copies each key into that `.env` file and protects it with the other
 credential paths. `copiedKeys` gives the outcome for each copy. A file that
 already holds another real value keeps it. The step stops when git does not
-ignore the file, because the key would then be committed.
+ignore the file, because the key would then be committed. A `--copy-to` file
+outside the repository is refused, because no baseline can protect it.
+
+When the developer keeps the key in a file outside the project, name that file
+with `--env-path`, and copy the key into the app's own `.env`:
+
+```bash
+copilotkit onboard credentials --model-key OPENAI_API_KEY \
+  --env-path ~/keys/.env --copy-to .env --json
+```
+
+Without `--copy-to`, the `next` field of the answer names this command for the
+outside file.
 
 It needs a bound run and exits zero for every answer. A `stopped` answer files
 the stop report itself. It never prints a key.
 
+`--model-key`, and `--key` for `onboard model-key`, take an environment
+variable name: letters, digits, and underscores, not starting with a digit.
+Mixed case is allowed, for example `GitHubToken`. Any other value is a usage
+error, and the step checks and copies nothing. The step copies a valid name the
+CLI cannot probe too, because the vendor is the developer's choice.
+
 ### A command, subcommand, or flag that should exist is rejected
 
 `npx` keys its cache on the spec string, so `copilotkit@latest` can keep serving
@@ -1638,6 +1779,12 @@ Release ordering: merge the CopilotKit starter before releasing this command. Th
 
 ## Local evaluation candidate setup
 
+Local evaluation is how the CLI offers self-hosting: `init` lists it as
+"Self-hosted: try it on your machine (Docker)". It runs the full stack on the
+developer's machine. The CLI does not install into a cluster; for that, use the
+[self-hosting guide](https://docs.copilotkit.ai/intelligence/self-hosting) and its
+Helm chart.
+
 This preview accepts macOS with Docker Desktop and Linux with rootful Docker Engine.
 The CLI checks daemon identity and refuses unknown engines, rootless Docker, Podman,
 non-Desktop macOS engines, Windows, and Docker Desktop on Linux. The Windows init picker

package/cli-build-info.json

@@ -2,20 +2,20 @@
   "schemaVersion": 1,
   "package": {
     "name": "copilotkit",
-    "version": "4.23.1"
+    "version": "4.25.0"
   },
   "intelligence": {
-    "commit": "84454c6457dc7f0bca01f5f04ff52b2c1abec0e2"
+    "commit": "9d0e411b31a75cac62342c22a7da942463eaca55"
   },
   "copilotKit": {
-    "submittedInput": "f835ce816112541654ded07162c2cc8ddf4f3f2c",
-    "commit": "f835ce816112541654ded07162c2cc8ddf4f3f2c"
+    "submittedInput": "1477c8eab6f88833fa93236fe766746c9800a991",
+    "commit": "1477c8eab6f88833fa93236fe766746c9800a991"
   },
   "channel": "production",
-  "triggeringActor": "dustywusty",
+  "triggeringActor": "BenTaylorDev",
   "workflow": {
-    "runId": "36956555306",
-    "runUrl": "https://github.com/CopilotKit/Intelligence/actions/runs/36956555306"
+    "runId": "37398681686",
+    "runUrl": "https://github.com/CopilotKit/Intelligence/actions/runs/37398681686"
   },
   "validationResult": "passed",
   "ag2": {
@@ -24,5 +24,5 @@
     "revision": "main",
     "pinned": false
   },
-  "builtAt": "2026-10-02T02:40:10Z"
+  "builtAt": "2026-10-06T01:22:51Z"
 }

package/exporters/langgraph/README.md

@@ -86,6 +86,27 @@ and integers outside the JavaScript safe range fail export instead of silently
 changing their values. Task exceptions are exported as their Python `repr`
 (type and message), matching persisted LangGraph task errors.
 
+Pydantic v2 models, including AG-UI `Context`, export through their Python-mode
+serialization contract with wire aliases and subclass fields. Nested models,
+extra fields, and meaningful nulls survive; a model's own serializers still
+control its representation (AG-UI omits unset optional fields). The resulting
+tree must contain supported JSON values. Bytes, dates, sets, arbitrary objects,
+non-string keys, non-finite numbers, and unsafe integers are rejected rather than
+coerced. This does not add model deserialization permissions to the checkpointer.
+Use the application's existing trusted deserialization configuration.
+Pydantic 2.12 or later is required for reliable nested model serialization.
+Older versions can reject acyclic recursive models or AG-UI Context inside
+`Any` fields. If model serialization fails on those versions, export stops with
+an upgrade message and retains the original exception as its cause; it does not
+retry with a lossy representation. Errors from application model serializers
+still require fixing the serializer if they persist after upgrading.
+
+Export fidelity and replay support are separate: native LangChain `file` and
+`audio` blocks remain intact in the export, but the current importer renders
+them as unresolved placeholders. Inline `image_url` data retains its bytes and
+MIME type through replay. Export success alone does not establish full media
+parity or correct routing when resuming an imported conversation.
+
 ## Tests
 
 ```sh
@@ -104,6 +125,18 @@ snapshot equality and database bytes. It makes no model/provider calls. The
 captured synthetic native snapshot in `fixtures/langgraph/checkpointer-native.jsonl`
 is consumed by TypeScript contract tests.
 
+`python/context_fixture.py` creates real AG-UI models in SQLite, reopens the
+store, and exports pending frontend, pending native, and completed interactions.
+The native test checks source rows and file bytes; the loader's
+`langgraph-context.spec.ts` checks the captured snapshots through database import,
+state/message replay, checkpoint provenance, and repeat-import deduplication.
+Regenerate that capture with:
+
+```sh
+python libs/import-langgraph/python/context_fixture.py libs/import-langgraph/fixtures/context.jsonl
+pnpm nx test @cpki/import-loader -- src/langgraph-context.spec.ts
+```
+
 ## Replay an application’s custom A2UI catalog
 
 When native `render_a2ui` calls omit `catalogId`, supply the original application catalog explicitly:

package/exporters/langgraph/export_checkpointer.py

@@ -7,6 +7,7 @@ from dataclasses import asdict, is_dataclass
 from math import isfinite
 
 from langchain_core.messages import BaseMessage
+from pydantic import BaseModel, VERSION as PYDANTIC_VERSION
 
 
 def json_value(value):
@@ -24,6 +25,21 @@ def json_value(value):
         return repr(value)
     if isinstance(value, BaseMessage):
         return json_value(value.model_dump(mode='json'))
+    if isinstance(value, BaseModel):
+        # AG-UI Context and other framework models use Pydantic's wire aliases.
+        # Python mode leaves non-JSON values intact for the strict checks below
+        # (JSON mode can coerce bytes, dates, sets and non-string keys).
+        try:
+            dumped = value.model_dump(mode='python', by_alias=True, serialize_as_any=True)
+        except (ValueError, TypeError, AttributeError) as error:
+            if tuple(map(int, PYDANTIC_VERSION.split('.')[:2])) < (2, 12):
+                raise ValueError(
+                    f'Cannot export {type(value).__name__} with Pydantic {PYDANTIC_VERSION}. '
+                    'Upgrade to Pydantic 2.12 or later for nested model serialization; '
+                    'if the error persists, check the model serializer.'
+                ) from error
+            raise
+        return json_value(dumped)
     if is_dataclass(value) and not isinstance(value, type):
         return json_value(asdict(value))
     if hasattr(value, '_asdict'):