copilotkit 4.23.1 → 4.24.0

package/README.md

@@ -321,12 +321,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 \
@@ -365,10 +396,47 @@ from the declared one. `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. A
+managed run with `local_offered: false` was never offered local. 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 +1018,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
@@ -1279,7 +1347,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`,
@@ -1430,11 +1498,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

package/cli-build-info.json

@@ -2,20 +2,20 @@
   "schemaVersion": 1,
   "package": {
     "name": "copilotkit",
-    "version": "4.23.1"
+    "version": "4.24.0"
   },
   "intelligence": {
-    "commit": "84454c6457dc7f0bca01f5f04ff52b2c1abec0e2"
+    "commit": "414f50da283d14f22e2b350dff662b4b18cb1017"
   },
   "copilotKit": {
-    "submittedInput": "f835ce816112541654ded07162c2cc8ddf4f3f2c",
-    "commit": "f835ce816112541654ded07162c2cc8ddf4f3f2c"
+    "submittedInput": "c88a2dd2a4c0",
+    "commit": "c88a2dd2a4c024e956e3f88b6b86d5715951e284"
   },
   "channel": "production",
-  "triggeringActor": "dustywusty",
+  "triggeringActor": "BenTaylorDev",
   "workflow": {
-    "runId": "36956555306",
-    "runUrl": "https://github.com/CopilotKit/Intelligence/actions/runs/36956555306"
+    "runId": "37064724012",
+    "runUrl": "https://github.com/CopilotKit/Intelligence/actions/runs/37064724012"
   },
   "validationResult": "passed",
   "ag2": {
@@ -24,5 +24,5 @@
     "revision": "main",
     "pinned": false
   },
-  "builtAt": "2026-10-02T02:40:10Z"
+  "builtAt": "2026-10-02T21:07:52Z"
 }

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'):