copilotkit 4.17.0 → 4.18.0

package/README.md

@@ -343,7 +343,9 @@ Its first prompt records the coding agent with `onboard identify`, including whe
 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.
 The event records a missing id as `unknown`, and the coding agent the environment
-shows as `detected_coding_agent`. Channel setup stage events include
+shows as `detected_coding_agent`. `cli.onboarding.started` also carries
+`detected_coding_agent`, because a run that stops before `onboard identify` sends
+no identify event. 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.
 
@@ -509,6 +511,23 @@ 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.
 
+## Import Strands Python History
+
+Run `copilotkit import --source strands-python --dry-run` to preview local
+Strands Python sessions. Both `FileSessionManager` records and
+`SnapshotSessionManager` snapshots are supported. Set the source root, stable
+source identity and explicit format through the
+[`STRANDS_PY_IMPORT_*` variables](../../libs/import-strands-python/README.md).
+Omit `--dry-run` to use the normal agent mapping and upload flow.
+
+Import an idle store. Extraction reads native files without creating an agent,
+calling a model or tool, or restoring a session. Snapshot imports use the latest
+saved view; they do not merge older snapshots into an invented transcript.
+Unavailable event timestamps remain absent. Native state and pending interaction
+identity are retained; routing a continuation to the original agent is separate.
+Use `ag-ui-strands>=0.4.1` when generating new sources that include frontend-tool
+results. Import cannot repair placeholders already saved by older adapters.
+
 ## Managed Channels
 
 `copilotkit channels` connects a hosted Intelligence project to Slack or
@@ -903,6 +922,20 @@ exist yet. After the credential step creates it, run
 Later changes still fail the audit. The same rule applies to
 `.copilotkit/project.json`. Missing source files remain protected.
 
+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.
+
+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
+repository, and `git status` there reads your whole home directory. A run that
+starts in such a project takes the file baseline instead, and the report names
+the repository it did not use. A run that starts in the home directory itself
+still uses its repository.
+
 ## Version Control
 
 Outside a repository, `copilotkit init` runs `git init` in the new app and makes
@@ -912,7 +945,9 @@ before you start editing.
 Inside a repository you already have, it does neither. A second `git init` would
 make the new app a nested repository: commits made in it would go to the inner
 repository, while the outer one saw only an untracked directory. The CLI names
-the repository it found and leaves the new app for you to commit.
+the repository it found and leaves the new app for you to commit. A repository
+at your home directory, or above it, does not count here, so an app created below
+it gets its own `git init`.
 
 The project binding is recorded at that repository's root, so every directory in
 it resolves to the same project, and the run says where it went. If the root
@@ -1057,9 +1092,10 @@ checks.
 `verify` works the port out from the project rather than assuming one. In order:
 
 1. `--runtime-url`, when you pass it.
-2. `"runtimeUrl"` in `.copilotkit/project.json` — an absolute URL you add by
-   hand for a project whose runtime is somewhere none of the below can find it.
-   The CLI never writes this field and never removes one you wrote.
+2. `"runtimeUrl"` in `.copilotkit/project.json` — an absolute URL for a
+   project whose runtime is somewhere none of the below can find it. Add it by
+   hand, or let `project select --runtime-url <url>` or
+   `onboard runtime-url --url <url>` write it. The CLI never removes one.
 3. `COPILOTKIT_RUNTIME_URL` in the project's `.env` / `.env.local`, when it is
    absolute.
 4. The port the app's own dev configuration declares: `PORT` in its env files,
@@ -1235,6 +1271,28 @@ 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.
 
+### `verify` probes port 3000 while the app runs on another port
+
+A dev server whose port is taken moves to the next free one without asking. A
+project that `init --create` made records no runtime URL, so `verify` assumes
+port 3000. Record the URL the server reports once it is up:
+
+```bash
+copilotkit onboard runtime-url --url http://localhost:3001/api/copilotkit
+```
+
+It writes `runtimeUrl` into the `.copilotkit/project.json` that governs the
+current directory and changes nothing else. It mints no key and does not touch
+`.env`, unlike `project select --runtime-url`, which selects the project again.
+It needs no bound run. The URL must name the mount path: a bare
+`http://localhost:3001` is refused, because `verify` would probe `/`. With no
+project record, it writes nothing and exits non-zero.
+
+An onboarding run protects the record once it selects the project. When the
+bound run protects it, the command moves that baseline with its own write, so
+the next `onboard audit` still passes. It refuses a record that changed since
+the baseline, so a write it did not make is never absorbed.
+
 ### A model key has no credits or is rejected
 
 A key with no credits passes every static check. The first model call then
@@ -1264,6 +1322,43 @@ 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.
 
+### An onboarding run stops while it selects the project
+
+The onboarding graph settles the project, its key, and the Learning Container
+with one step. Run it from the app directory whose `.env` receives the key:
+
+```bash
+copilotkit onboard credentials --json
+copilotkit onboard credentials --create billing-portal \
+  --runtime-url http://localhost:3000/api/copilotkit --json
+```
+
+With no project flag, the step reuses a project that this directory already
+binds with a key. Otherwise it asks for the project name. With `--create` or
+`--project`, it runs `project select`, retries once when no key was written, and
+checks the record and the key. Then it reads the default Learning Container.
+
+Read `status`:
+
+- `ready`: the project, key, and container are settled.
+- `needs-developer`: `question` names the project name or the app directory
+  that the step needs.
+- `stopped`: `stopReason` names the check, the exact file or code, and the
+  friction category for the stop report.
+
+When the project is settled, the same step checks the model credential:
+
+```bash
+copilotkit onboard credentials --model-key OPENAI_API_KEY --json
+```
+
+It asks the vendor about each key, as `onboard model-key` does. When every key
+settles, it protects the credential paths for the run's audit. A missing or
+refused key is a `needs-developer` answer.
+
+It needs a bound run and exits zero for every answer. A `stopped` answer files
+the stop report itself. It never prints a key.
+
 ### A command, subcommand, or flag that should exist is rejected
 
 `npx` keys its cache on the spec string, so `copilotkit@latest` can keep serving
@@ -1409,3 +1504,30 @@ The destination must not already exist. The CLI validates every bundle before it
 If a download or validation fails, the CLI leaves no partial destination.
 Container IDs must be unique and belong to the selected project. Select up to 50 containers.
 Multiple containers use one product API batch request. If any container fails, the whole request fails.
+
+## Import standalone LangGraph history
+
+Use `copilotkit import --source langgraph --langgraph-snapshot native.jsonl`
+for a Python FastAPI application that does not expose LangGraph Server APIs.
+Export saved checkpoints with the helper shipped at
+`exporters/langgraph/export_checkpointer.py` in this CLI package (with its guide
+at `exporters/langgraph/README.md`). Supply explicit
+native thread/graph selections when graphs share storage. See the
+[LangGraph exporter guide](../../libs/import-langgraph/README.md) for the native
+contract, async export example, discovery rules, source limitations and validation.
+The existing API credentials, agent map, dry-run and replace options apply.
+The snapshot retains native IDs and checkpoint provenance; replay does not prove
+continuation on the original native session.
+
+## Replay an application’s custom A2UI catalog
+
+When native `render_a2ui` calls omit `catalogId`, supply the original application catalog explicitly:
+
+```sh
+copilotkit import --source langgraph --langgraph-snapshot native.jsonl \
+  --agent-map agent-map.json --a2ui-default-catalog-id copilotkit://app-dashboard-catalog -y
+```
+
+The destination frontend must register that catalog. This option works with all import sources and applies to every selected conversation; import applications with different defaults separately. Explicit native `catalogId` values and native A2UI operation payloads take precedence. Native tool arguments/results are preserved; the setting only controls reconstructed UI. Without the option, existing replay behavior is unchanged. Invalid empty/whitespace identifiers fail before upload. No catalog is inferred from message prose.
+
+API callers can set `replayConfig: { defaultCatalogId: "copilotkit://app-dashboard-catalog" }` on each normalized conversation. An unchanged source identity is still deduplicated: changing this option does not update an existing import. Use the existing `--replace` workflow to regenerate its imported history, after accounting for any destination changes.

package/cli-build-info.json

@@ -2,20 +2,20 @@
   "schemaVersion": 1,
   "package": {
     "name": "copilotkit",
-    "version": "4.17.0"
+    "version": "4.18.0"
   },
   "intelligence": {
-    "commit": "f6f91f8357a9058dcda3f2ef07a3283e23ddb9e8"
+    "commit": "3a9266b5fa673a4974ad204d131ed63d5696dc00"
   },
   "copilotKit": {
-    "submittedInput": "0c8647a7f4ec",
-    "commit": "0c8647a7f4ecf565e58405642539c9d9744f62c5"
+    "submittedInput": "70d1f3c0a832",
+    "commit": "70d1f3c0a832d6274e2fe710e24102f6429f14f4"
   },
   "channel": "production",
   "triggeringActor": "BenTaylorDev",
   "workflow": {
-    "runId": "36178536102",
-    "runUrl": "https://github.com/CopilotKit/Intelligence/actions/runs/36178536102"
+    "runId": "36480955998",
+    "runUrl": "https://github.com/CopilotKit/Intelligence/actions/runs/36480955998"
   },
   "validationResult": "passed",
   "ag2": {
@@ -24,5 +24,5 @@
     "revision": "main",
     "pinned": false
   },
-  "builtAt": "2026-09-25T19:17:42Z"
+  "builtAt": "2026-09-28T20:43:08Z"
 }

package/exporters/langgraph/README.md

@@ -0,0 +1,118 @@
+# LangGraph import
+
+`@cpki/import-langgraph` normalizes saved LangGraph Server history and standalone
+Python graph checkpoint exports for the shared Intelligence import pipeline.
+
+## Standalone FastAPI applications
+
+FastAPI and AG-UI do not imply a LangGraph Server thread API. Use the compiled
+graph and its configured checkpointer in the application's own environment.
+The exporter does not open SQL tables, invoke graph nodes, answer interrupts,
+or write checkpoints. It requires public `aget_state_history`, `aget_state`,
+`get_output_jsonschema`, and optionally the saver's `alist` API.
+
+Copy `python/export_checkpointer.py` into your application tooling (also shipped
+in the CLI package under `exporters/langgraph/`). Run this with the application's
+existing dependency versions and matching compiled graph:
+
+```python
+import json
+from export_checkpointer import export_thread
+
+# graph already has the application's durable checkpointer attached.
+# Obtain this selection from your application's thread/graph registry.
+configs = [{"configurable": {"thread_id": "native-thread-id", "checkpoint_ns": ""}}]
+with open("native.jsonl", "x", encoding="utf-8") as output:
+    for config in configs:
+        record = await export_thread(
+            graph, config, source_id="production-chat-store", graph_id="chat"
+        )
+        output.write(json.dumps(record, allow_nan=False) + "\n")
+```
+
+This snippet belongs inside your application's async export routine with the
+checkpointer open. Use an idle source or a consistent read-only database copy.
+The exporter detects a changed head checkpoint and asks you to retry. It cannot
+provide a transaction spanning arbitrary custom storage implementations. Never
+run startup code that initializes or mutates the retained production store merely
+to export it. Preserve the same source label when exporting a copy of that store.
+
+If one graph owns the entire selected namespace, discover configs with
+`async for config in discover_threads(saver, graph_owns_namespace=True)`.
+`checkpoint_ns` defaults to the root namespace `""`; select another namespace
+explicitly with a compiled graph that supports reading it. Do not infer ownership
+when multiple graphs share the same saver and namespace. Supply explicit configs
+from the application's registry for each graph instead. Missing graph ownership
+cannot be recovered from the generic saver contract. Stores without discovery
+support can still export known thread IDs.
+
+```sh
+copilotkit import --source langgraph --langgraph-snapshot native.jsonl \
+  --agent-map agent-map.json --unrecoverable imported-unknown --dry-run -y
+```
+
+`agent-map.json` maps the declared graph key to your configured Intelligence agent,
+for example `{"chat":"beautiful-chat"}`. Remove `--dry-run` after inspecting the
+preview. Existing API credentials and `--replace` behavior apply. Snapshot mode
+makes no LangGraph Server requests. Invalid records, conflicting graph identity,
+duplicate conversation identities, and histories that do not follow a newest-first
+parent checkpoint chain fail enumeration before opening a batch.
+Treat the file as sensitive conversation data; it may include user messages,
+attachments, graph state and interrupt values. No database credentials or runtime
+configuration are exported by the helper.
+
+## Fidelity and identity
+
+The current checkpoint's messages and output-schema-projected state are
+canonical. Available text, media, tool calls/results, frontend tool requests and
+native task interrupts reuse the existing converter and replay pipeline. The
+exporter uses the head read to apply completed pending writes. It preserves
+native task/interrupt IDs and checkpoint/parent selectors as observed provenance.
+Exports follow the current head’s ancestor chain; sibling branches are excluded.
+Those selectors never authorize a rewind, fork or outbound route.
+
+The opaque dedup key is a JSON tuple of format, source ID, graph ID, namespace and
+native thread ID. It is stable across checkpoint revisions and distinct across
+stores/namespaces. It is not an executable thread ID. `nativeSource.threadId`
+retains the exact native ID. `sourceId` is a stable non-secret store/deployment
+label; `graphId` selects interpretation and does not prove physical isolation.
+Continuation to the original session is separate from replay/import support.
+
+Checkpointers do not supply Server run records. Imported transcripts therefore
+use a synthetic run with unknown status unless a native failure is recorded;
+metadata explicitly marks run boundaries unavailable. Middleware-only UI or HTML
+never saved by the source cannot be reconstructed. Unknown non-JSON native values
+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.
+
+## Tests
+
+```sh
+python -m pip install -r libs/import-langgraph/python/requirements-test.txt
+pnpm nx run @cpki/import-langgraph:test-native
+pnpm nx test @cpki/import-langgraph
+```
+
+Install the workspace Node dependencies with `pnpm install --frozen-lockfile`
+before running the native tests. They emit JSON Schema from the actual TypeScript
+importer schema and validate every fresh export against it.
+
+The SQLite test runs a local graph with a genuine interrupt, checks checkpoint
+and pending-write rows before/after export, reopens the database and compares
+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.
+
+## Replay an application’s custom A2UI catalog
+
+When native `render_a2ui` calls omit `catalogId`, supply the original application catalog explicitly:
+
+```sh
+copilotkit import --source langgraph --langgraph-snapshot native.jsonl \
+  --agent-map agent-map.json --a2ui-default-catalog-id copilotkit://app-dashboard-catalog -y
+```
+
+The destination frontend must register that catalog. This option works with all import sources and applies to every selected conversation; import applications with different defaults separately. Explicit native `catalogId` values and native A2UI operation payloads take precedence. Native tool arguments/results are preserved; the setting only controls reconstructed UI. Without the option, existing replay behavior is unchanged. Invalid empty/whitespace identifiers fail before upload. No catalog is inferred from message prose.
+
+API callers can set `replayConfig: { defaultCatalogId: "copilotkit://app-dashboard-catalog" }` on each normalized conversation. An unchanged source identity is still deduplicated: changing this option does not update an existing import. Use the existing `--replace` workflow to regenerate its imported history, after accounting for any destination changes.

package/exporters/langgraph/export_checkpointer.py

@@ -0,0 +1,125 @@
+"""Read-only LangGraph export helpers. Run inside the application's Python environment.
+
+The caller owns checkpointer lifecycle, credentials and graph/thread selection.
+This module never invokes a graph or opens a database directly.
+"""
+from dataclasses import asdict, is_dataclass
+from math import isfinite
+
+from langchain_core.messages import BaseMessage
+
+
+def json_value(value):
+    """Convert native messages/tasks into JSON without lossy string fallbacks."""
+    if value is None or isinstance(value, (str, bool)):
+        return value
+    if isinstance(value, int):
+        if abs(value) > 9007199254740991:
+            raise ValueError('Native integer exceeds the JavaScript safe integer range')
+        return value
+    if isinstance(value, float) and isfinite(value):
+        return value
+    if isinstance(value, Exception):
+        # Match LangGraph's persisted task-error representation (type + message).
+        return repr(value)
+    if isinstance(value, BaseMessage):
+        return json_value(value.model_dump(mode='json'))
+    if is_dataclass(value) and not isinstance(value, type):
+        return json_value(asdict(value))
+    if hasattr(value, '_asdict'):
+        return json_value(value._asdict())
+    if isinstance(value, dict):
+        if any(not isinstance(key, str) for key in value):
+            raise ValueError('Native data contains non-string JSON object keys')
+        return {key: json_value(item) for key, item in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [json_value(item) for item in value]
+    raise ValueError(f'Native data is not losslessly JSON serializable: {type(value).__name__}')
+
+
+def checkpoint_ref(config):
+    """Keep checkpoint selectors only; never export source credentials/configuration."""
+    if config is None:
+        return None
+    selected = config['configurable']
+    return {key: selected[key] for key in ('thread_id', 'checkpoint_ns', 'checkpoint_id', 'checkpoint_map') if key in selected}
+
+
+async def discover_threads(checkpointer, *, graph_owns_namespace, checkpoint_ns=''):
+    """Discover IDs via public saver API in a namespace owned by ONE graph.
+
+    Do not use on a store shared by graphs without a separate ownership registry.
+    Instead supply explicit per-graph thread configs from that registry.
+    """
+    if graph_owns_namespace is not True:
+        raise ValueError('Discovery requires explicit single-graph namespace ownership; supply selected configs for shared stores')
+    seen = set()
+    async for item in checkpointer.alist(None):
+        selected = item.config['configurable']
+        if selected.get('checkpoint_ns', '') != checkpoint_ns:
+            continue
+        thread_id = selected['thread_id']
+        if thread_id not in seen:
+            seen.add(thread_id)
+            yield {'configurable': {'thread_id': thread_id, 'checkpoint_ns': checkpoint_ns}}
+
+
+async def export_thread(graph, config, *, source_id, graph_id):
+    """Export one selected native thread through public graph history reads.
+
+    Use an idle source or a consistent read-only copy and the matching compiled
+    graph. History is the current head's ancestry, newest-first, including pending
+    task writes/interrupts. Sibling branches are excluded.
+    A checkpoint revision in config is rejected: this exports the current head,
+    not a branch rewind. JSON output is data, never continuation authorization.
+    """
+    if not source_id or not graph_id:
+        raise ValueError('source_id and graph_id must be nonempty stable labels')
+    selected = config['configurable']
+    if not selected.get('thread_id') or selected.get('checkpoint_id'):
+        raise ValueError('Select a native thread ID without a checkpoint revision')
+    namespace = selected.get('checkpoint_ns', '')
+    history = []
+    async for state in graph.aget_state_history(config):
+        if state.metadata and state.metadata.get('graph_id', graph_id) != graph_id:
+            raise ValueError('Recorded graph ownership conflicts with selected graph')
+        history.append({
+            'values': json_value(state.values),
+            'next': list(state.next),
+            'tasks': json_value(state.tasks),
+            'checkpoint': checkpoint_ref(state.config),
+            'parent_checkpoint': checkpoint_ref(state.parent_config),
+            'metadata': json_value(state.metadata),
+            'created_at': state.created_at,
+        })
+    if not history:
+        raise ValueError('No saved checkpoints for the selected native thread')
+    # Detect a concurrent source advance instead of claiming a consistent export.
+    head = await graph.aget_state(config)
+    if checkpoint_ref(head.config) != history[0]['checkpoint']:
+        raise ValueError('Native checkpoint advanced during export; retry on an idle source')
+    # aget_state applies completed pending writes to the authoritative head.
+    history[0]['values'] = json_value(head.values)
+    history[0]['next'] = list(head.next)
+    history[0]['tasks'] = json_value(head.tasks)
+    # Public history can contain sibling branches after a fork. Export only the
+    # current head's ancestor chain so adjacency has the same meaning on import.
+    revisions = {entry['checkpoint']['checkpoint_id']: entry for entry in history}
+    lineage = []
+    seen = set()
+    entry = history[0]
+    while entry is not None:
+        revision = entry['checkpoint']['checkpoint_id']
+        if revision in seen:
+            raise ValueError('Native checkpoint ancestry contains a cycle')
+        seen.add(revision)
+        lineage.append(entry)
+        parent = entry['parent_checkpoint']
+        entry = revisions.get(parent['checkpoint_id']) if parent else None
+    return {
+        'format': 'copilotkit.langgraph.checkpointer.v1',
+        'sourceId': source_id, 'graphId': graph_id,
+        'config': {'thread_id': selected['thread_id'], 'checkpoint_ns': namespace},
+        'outputSchema': json_value(graph.get_output_jsonschema()),
+        'history': lineage,
+    }