copilotkit 4.28.0 → 4.30.0

package/README.md

@@ -120,6 +120,18 @@ carried as `suggested_name`:
 }
 ```
 
+Any other failure carries what is known about its cause: `code` (such as
+`CLI_REQUEST_TIMEOUT` or `ENOENT`), `http_status` for a failed request (`0`
+when no answer arrived), and `syscall` for a failed file operation (such as
+`open`). `failed_step` says whether listing or creating the project failed. A
+taken `--create` name also carries `taken_slug`, the slug of the project that
+has the name.
+
+`onboard credentials` runs the selection once more after a timeout, a network
+failure, a server error, or a missing file, then stops and names the cause.
+When a create request failed and the second try finds the name taken, the
+first try made that project, so the step selects it by `taken_slug`.
+
 The interactive picker offers the same name and never applies it silently:
 press Enter again to take it, or type a different one.
 
@@ -263,9 +275,17 @@ URL for manual sign-in. Either way, it keeps reading the same process until its
 terminal event. A failed sign-in prints one final failure object and exits
 nonzero.
 
-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.
+The bundled onboarding prompt explains that a free CopilotKit account is required
+to continue setup. Sign-in does not start a paid CopilotKit Intelligence
+subscription or commit you to cloud hosting.
+
+The onboarding prompt runs `login --json --onboarding`. In that mode, the agent
+keeps reading the process after it shows the sign-in message. If nobody approves
+the code within 90 seconds, the CLI writes a `pause` record. Its `message` tells
+the developer to reply "done" after they sign in, and its `action` tells the
+agent to end its turn and read the same process again on the reply. The
+`completed` record carries an `action` that names the next step. Plain
+`login --json` writes neither.
 
 ### Signing in when the browser is on another machine
 
@@ -396,8 +416,8 @@ 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`. The agent also passes `--model` with
+Its first prompt records the coding agent with `onboard begin`, which runs
+`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 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
@@ -422,9 +442,12 @@ where it found it in `detected_coding_agent_source`. `cli.onboarding.started` al
 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. A run sends `cli.onboarding.started` once. A
-later `onboard start` for the same run and intent prints the first prompt again
-but sends no second start, so the repeat shows only as `prompt_repeat` on
-`cli.onboarding.prompt_served`. A feature run that reads a node of another
+later `onboard start` for the same run and intent sends no second start. Before
+the run reads a second step, it prints the first prompt again, so the repeat
+shows only as `prompt_repeat` on `cli.onboarding.prompt_served`. After that, it
+prints no prompt: it names the step the run is at, skipping `subagent/` briefs.
+It then sends `cli.onboarding.prompt_served` for that step with `reentry: start`,
+so `prompt_repeat` still counts the repeat. A feature run that reads a node of another
 feature moves to that feature's intent. It sends `cli.onboarding.intent_switched`
 with `previous_intent` and the new `onboarding_intent`, and every later event
 carries the new intent. Before sign-in, the first prompt records where the
@@ -517,7 +540,20 @@ A later `onboard start` that re-enters the same run keeps its project.
 ### 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
+`stopped/run-failed`. The read requires the reason the run broke:
+
+```bash
+npx --yes copilotkit@latest onboard read stopped/run-failed --reason build --message "next build failed on a missing export"
+```
+
+`--reason` is one of `build`, `typecheck`, `dependency-install`, `model-call`,
+`docs-gap`, or `other`. `--message` is optional: one line,
+guarded like a friction report. A read with no reason, or an unknown one, serves
+nothing and names the flag to add. The failing command is usually the agent's own,
+such as `next build` or `tsc`, so the CLI cannot see it, and the reason is how
+`cli.onboarding.terminal_reached` names it (`stop_reason`, `stop_reason_text`).
+
+That node used to be the end of the run. 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.
 
@@ -546,6 +582,21 @@ 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.
 
+### When the developer says no
+
+A developer who declines, such as **no** or **not now** at the setup message, is not a
+run that broke. The run reads `stopped/declined`, which thanks them, relays what the
+run changed, and offers `onboard restore`:
+
+```bash
+npx --yes copilotkit@latest onboard read stopped/declined --message "<the developer's reason>"
+```
+
+`--message` is optional and guarded like a friction report. The read takes no
+`--reason`, and `onboard read stopped/run-failed --reason developer-declined` is
+refused with the declined read to run instead, so a decline has one path. It reaches
+`cli.onboarding.terminal_reached` as `terminal: declined`.
+
 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
@@ -614,7 +665,27 @@ copilotkit init -n my-agent -f langgraph-py \
   `init` prints the variable name and never the value. A real value already in
   the app is kept. A missing or unreadable file stops `init` before it clones
   anything. The .NET starter keeps its key in `dotnet user-secrets`, so this flag
-  does not fill it.
+  does not fill it. With `--model-vendor`, the key copied is that vendor's.
+  Without it, and with `-f`, the key in the file picks the vendor: a file with
+  the starter's own key keeps the starter's model, and a file with one other
+  vendor's key switches the starter to that vendor. A file with keys for
+  several other vendors, or only for a vendor the starter does not run, stops
+  `init` before it clones anything, and names the flag to pass.
+- `--model-vendor <vendor>` sets the vendor of the agent's model: `openai`,
+  `anthropic`, `google`, or `openai-compatible`. `init` writes
+  `COPILOTKIT_AGENT_MODEL=<vendor>:<model>` into the env file the agent reads
+  (`openai:<model>` for an OpenAI-compatible provider),
+  and asks for that vendor's key instead of the starter's default key. A vendor
+  that the starter cannot run is refused before anything is cloned. The
+  AgentCore, .NET and AG2 starters take no `--model-vendor`. When you pick the
+  framework at a terminal, without `--no-key-prompt`, `init` asks for the vendor
+  and model after it.
+- `--model-id <id>` names the vendor's model. Without it, `init` uses a model the
+  vendor serves today: `gpt-5-mini`, `claude-sonnet-5` or `gemini-3.8-flash`.
+- `--base-url <url>` is the API base URL of an OpenAI-compatible provider, written
+  as `OPENAI_BASE_URL`. It goes with `--model-vendor openai-compatible` only,
+  which also needs `--model-id`. A URL that holds a user, password, or key is
+  refused: the key goes in the key file.
 
 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:
@@ -1025,7 +1096,8 @@ OPENAI_API_KEY=your-key-here
 (Replace `your-key-here` with your real key — placeholder-shaped values are
 rejected by the dev preflight described below.)
 
-The ADK template uses `GOOGLE_API_KEY`. The A2A template uses both `OPENAI_API_KEY` and `GOOGLE_API_KEY`.
+The ADK and A2A templates use `GOOGLE_API_KEY`. The A2A template sets one model,
+`COPILOTKIT_AGENT_MODEL=google:gemini-3.8-flash`, for all three of its agents.
 
 For threads-enabled scaffolds, `npm run dev` verifies the required key(s)
 before starting anything: if a key is unset, empty, or still an obvious
@@ -1074,6 +1146,44 @@ for the app. A new onboarding run,
 untrack `.env` again. The Channels setup commands still read and write `.env`
 only.
 
+## Notification when an onboarding run ends
+
+An onboarding run can take an hour, so you can leave while it works. When the run
+ends, the CLI shows one desktop notification on your computer:
+
+- "CopilotKit setup finished" when `onboard complete` records the end. The text
+  says that your app works, or that some checks are not done.
+- "CopilotKit setup stopped" when the run stops at `stopped/run-failed`,
+  `feature/stop`, or `feature/blocked-by-plan`.
+
+Open the window of your coding agent to read the report. A run shows one
+notification at its first end. After `onboard resume`, the run shows one more
+notification at its next end.
+
+The CLI uses `osascript` on macOS, `notify-send` on Linux, and a PowerShell toast
+on Windows. In these cases, the CLI shows no notification:
+
+- On CI, in a container, or in a sandbox.
+- Over SSH.
+- On Linux with no `DISPLAY` or `WAYLAND_DISPLAY`, or with no `notify-send`.
+
+The CLI waits at most 3 seconds for the notification, or 6 seconds on Windows.
+When the notification cannot show, the CLI prints nothing and the step
+continues.
+
+Set `COPILOTKIT_NO_NOTIFY=1` to turn the notification off.
+
+`cli.onboarding.completed`, and `cli.onboarding.terminal_reached` for the three
+stop nodes above, carry `notification`: `shown`, `skipped`, or `failed`.
+
+### Docs links in the closing report
+
+The closing report links to the AG-UI Streams and Learning docs. Each link carries
+`utm_source=cli&utm_medium=onboarding&utm_campaign=closeout` and
+`utm_content=streams` or `utm_content=learning`. A click that opens the page shows
+as a docs `$pageview` with that URL, in the same PostHog project as the CLI events.
+A click from a reader who blocks analytics does not show.
+
 ## Onboarding backups and restore
 
 `copilotkit onboard start` backs up the project before the run changes anything.
@@ -1588,6 +1698,16 @@ the coding agent, decides three things about it:
   `providerError`: `auth`, `quota`, `model-not-found`, `rate-limit` or `other`.
   It is read from that code, never from a status or a message.
   `verify --round-trip --json` reports both on `roundTrip` too.
+- When the check started the servers, a `run-error` that says the runtime could
+  not reach its agent (`fetch failed`, `ECONNREFUSED`) is tried again every
+  10 seconds, for up to 2 minutes. A Python agent installs its packages before
+  it listens, so a first run on a cold cache sends its chat message too early.
+  The outcome is recorded once, after the last try.
+- The first time the app answers in a run that read `proof/round-trip`, and
+  the whole proof check passed, the command also prints `earlyReport`
+  (`Tell the developer:` without `--json`): a short report that the app works,
+  with the frontend URL. The main agent shows it to the developer before the
+  slower checks run. The starter job's own proof check prints none.
 - When the same check fails three proof checks in a row, the command prints
   `Status: stopped`. A later `onboard proof-check` in the same attempt starts no
   server and prints the same stop. Recording the attempt with `onboard proof`
@@ -1738,13 +1858,24 @@ the value came from: `env-file` or `environment`.
 
 - `pass`: the vendor served a model call with the key.
 - `fail`: the vendor refused the key or the app's model. The cause is
-  `model_quota` (no credits), `model_auth` (a rejected key), or
-  `model_unavailable` (the vendor does not serve the app's model to this key).
+  `model_quota` (no credits), `model_auth` (a rejected key),
+  `model_unavailable` (the vendor does not serve the app's model to this key), or
+  `model_rate_limited` (OpenAI rate-limited two calls in a row, see below).
 - `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`.
+- `unsupported` or `undetermined`: the check did not settle it. A single 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`.
+
+When OpenAI answers the probe with a 429 that is not `insufficient_quota`, the
+command waits and asks once more. It waits as long as a `Retry-After` header in
+seconds says, up to 30 seconds, and 30 seconds when there is none. A 429 on the
+second call too is a `fail` with the cause `model_rate_limited`: one call with
+one output token cannot reach a normal limit, so the app's calls would be
+refused too. Any other second answer is read by the usual rules. `providerStatus`
+and `providerCode` in the JSON are the vendor's HTTP status and error code, and
+the onboarding event `cli.onboarding.credentials_checked` carries them as
+`model_key_provider_status` and `model_key_provider_code`.
 
 The probe proves the key, not the app's model. When `COPILOTKIT_AGENT_MODEL` names the
 app's model as `provider:model` or `provider/model`, for the same vendor as the key, the
@@ -1793,7 +1924,15 @@ reason `key-not-openai`. So a key in `.env.local` is checked against a base URL
 a file outside the app is checked against the right endpoint. When the shell and the
 services name different base URLs (the scheme and host compare without regard to case),
 the command sends nothing and reports `undetermined` with the reason
-`endpoint-conflict`. The JSON names the vendor `openai-compatible` and the endpoint's
+`endpoint-conflict`. Its `endpoints` names each place that sets a base URL: the
+variable, the env file or the shell or the setup answers, and the `origin` (scheme,
+host and port, never the path). `pathDiffers` marks two places with one origin and
+different paths. In `onboard credentials`, this answer pauses the step on the
+developer, as a missing key does: the question lists each base URL and asks which one
+the app uses, so the run does not plan or build on a key it never checked. `next` says
+how to change each kind of place: edit an env file, record a setup answer again with
+`onboard setup-answers --base-url`, or have the developer unset a shell variable and
+restart the coding agent. Once one base URL remains, the normal check runs. The JSON names the vendor `openai-compatible` and the endpoint's
 host as `endpointHost`. With `COPILOTKIT_AGENT_MODEL` set, the command sends a
 one-token chat with that model to `{base}/chat/completions` instead, which gives a
 real `pass` or `fail`. A key that the endpoint calls invalid is a `fail`, including
@@ -1882,6 +2021,11 @@ step reads it even after the coding agent lost its context:
 - The env-file answer, when git tracks the env file the key goes into or does
   not ignore it: `--env-line approved|alternative|declined`.
   `credentials/finalize-plan` reads it, so the developer is not asked twice.
+- On any route, `--learning declined` when the developer leaves Learning out.
+  `onboard credentials` then reads no Learning Container and records it as
+  `skipped` with the reason `developer-declined`. Recorded after that step, it
+  replaces the container the step found. `onboard proof-check` then asks for
+  no container, and the closing report says Learning is off.
 
 A later call replaces only the answers it names. The vendor flags replace the
 recorded vendor answer as a whole. With no flag, it prints what the run recorded
@@ -1910,6 +2054,12 @@ It prints `status`, the `message` to show word for word, the `open` lines, and
   **go** never answers: the developer names the file that holds it, or says
   "later". The message also holds every line that needs the developer's own
   answer, such as an env file to untrack or files with uncommitted changes.
+  For an existing app, the message first says what the run adds to the app,
+  what stays as it is, and which env file gets the CopilotKit key. The answers
+  **go** does not give come next, the key
+  first, and the optional settings with their defaults come last. An env-file
+  line leads with the recommended change and what it means for teammates, with
+  the git command under "Details".
 - `settled`: every line is answered. The run goes on to `credentials/plan`.
 - `needs-credentials`: an existing app on the managed route has no project
   finding yet. The command runs the read-only `onboard credentials` check
@@ -1953,6 +2103,97 @@ When `init --local --install` stops after it cloned the starter, it still
 installs the starter's dependencies, and its error says so or names the install
 command.
 
+#### The opening call: `onboard begin`
+
+After `onboard start`, the agent runs one call to reach the first message the
+developer acts on (PE-899):
+
+```bash
+copilotkit onboard begin --coding-agent codex --model gpt-5.6 --model-family gpt-5
+```
+
+It runs, in one process, the steps an agent used to run one by one: `onboard
+identify`, `onboard deployment --choice managed`, the session check that
+`login --json` makes first, the `sign-in-settled` checkpoint, and `onboard read`
+of the next prompt. Each step records the same event as before. The managed
+deployment it records is a default, not the agent's choice: the setup message
+shows it on its Hosting line, which says the hosted service is free to start,
+and the developer approves it with **go**. On the starter
+route, in a folder that holds no file of the developer's, it also prints the
+first setup message, as `onboard setup-message --target empty --json` prints it.
+A README in the folder leaves that message to `starter/setup`, which records the
+framework the README names first.
+
+- With no session, it records the agent and the deployment, then prints
+  `Sign-in needed` and the `login --json --onboarding` command. Sign-in stays its
+  own long-lived process.
+- `--local` records the agent and serves `deployment/choose-local`. A project
+  with a local stack gets that prompt without the flag.
+- `--vendor <vendor>` passes a model vendor the developer named to the setup
+  message.
+
+The separate commands still work, so a resumed run on an older prompt goes on.
+
+#### The starter fast path: `onboard starter`
+
+`onboard start` in an empty folder takes the starter route (PE-827). A folder
+counts as empty by the rule `init` builds by: no source folder, no dependency
+manifest and no `.env`. A README, a licence, ignore files and a `.env.example`
+are fine, so a repository created on GitHub takes it. The start must have no
+`--intent`. The start prints `Route: starter`, and
+`authenticate/start` then sends the run to `starter/setup` instead of the
+research. That node records a framework the README names, shows the setup message, then
+runs `onboard starter create`
+and `onboard starter prove`. It reads no research or plan prompts and changes no
+code. Any other folder keeps the research route.
+
+`onboard start --starter <starter-id> [--vendor <openai|anthropic|google>]`
+fills the framework, frontend and vendor lines with a starter the person picked
+on a website or docs page. It refuses a starter the CLI does not know and a
+vendor the starter does not take, before a run starts.
+`cli.onboarding.started` carries `onboarding_route`: `starter` or `research`.
+It also carries `git_available`, from one `git --version` run with a 3-second
+limit, and `git_major_version` when git names one. A missing git otherwise shows
+only later, as a failed command.
+
+`onboard starter` builds and proves a starter in an empty folder from the
+setup answers, with two commands. The agent runs them from the run
+folder:
+
+```bash
+copilotkit onboard starter create --framework langgraph-js --create support-bot --key-file ~/keys/openai.env
+copilotkit onboard starter status --wait
+copilotkit onboard starter prove
+copilotkit onboard starter status --wait
+```
+
+- `create` with no flags builds from the setup answers the run recorded, and
+  first records the run's path with `onboard classify`. It refuses a setup
+  with a line still open, and a framework and frontend with no starter.
+- `create` with flags builds the starter with the `init` command that
+  `starter/clone` runs: `--framework` takes the `init` starter id. It takes one of `--create`,
+  `--project` or `--local` (with `--defer-model` or `--model-config`), and one
+  of `--key-file` or `--key-later`. It also takes `--model-vendor`, `--model-id`,
+  `--base-url` and `--no-install`, as `init` does. Before it starts anything, it
+  checks the key in the key file with the model key check, and a refused key
+  creates nothing.
+- `prove` checks the model key in the app, starts the app, runs the round trip,
+  records the proof, and prints the closing report. With the key later, it
+  stops at the key check and prints, word for word, the line the developer adds
+  and the file it goes in. If the developer names a file that
+  holds the key instead, `prove --key-file <path>` checks the key there and
+  copies it into the file the app reads.
+- Each command records a job, starts a background worker, and waits for it for
+  up to 90 seconds. Some coding agents end a command at 2 minutes, and an
+  agent-run `init` takes a median of about 2 minutes. `status --wait` waits up
+  to 90 seconds again, and prints the step under way, the next command, or what
+  failed.
+
+The job record and its log are in `~/.copilotkit/onboarding-jobs/<run id>/`,
+never in the project, because `init` refuses a folder that holds files. The
+worker passes on the deployment flags the command got, such as `--deployment`
+and `--ops-api-url`.
+
 #### Model vendors in this release
 
 Onboarding offers a new agent only the vendors in this table. When onboarding
@@ -1966,20 +2207,34 @@ An existing agent keeps its own vendor and model. A vendor recorded with
 `--vendor-choice existing`, or a run that `onboard classify` placed on an
 existing agent, is never refused.
 
-| Framework                              | Vendors                                      |
-| -------------------------------------- | -------------------------------------------- |
-| Built-in CopilotKit agent              | OpenAI, OpenAI-compatible, Anthropic, Google |
-| ADK                                    | Google, OpenAI, OpenAI-compatible            |
-| Claude Agent SDK (Python, TypeScript)  | Anthropic                                    |
-| Every other framework and Custom agent | OpenAI, OpenAI-compatible                    |
-
-Anthropic and Google come to the other frameworks in a later release. Their
-CopilotKit middleware sends the page context as a second system message, after
-the user message. Anthropic and Google refuse that message order, so every chat
-fails. The built-in agent sends the context in one leading system message, and
-ADK puts it in its one system instruction. To use Anthropic or Google for a new
-agent now, choose the built-in CopilotKit agent. An existing agent on Anthropic
-or Google can see page context fail until a CopilotKit SDK release fixes it.
+| Framework                                                                                     | Vendors                                      |
+| --------------------------------------------------------------------------------------------- | -------------------------------------------- |
+| Built-in CopilotKit agent, Agno, LangGraph (Python, TypeScript, FastAPI), Mastra, Pydantic AI | OpenAI, OpenAI-compatible, Anthropic, Google |
+| ADK                                                                                           | Google, OpenAI, OpenAI-compatible, Anthropic |
+| Microsoft Agent Framework (Python), Strands Agents (Python, TypeScript)                       | OpenAI, OpenAI-compatible, Anthropic         |
+| Claude Agent SDK (Python, TypeScript)                                                         | Anthropic                                    |
+| Every other framework and Custom agent                                                        | OpenAI, OpenAI-compatible                    |
+
+The table comes from `apps/cli/starter-model-vendors.cjs`. A framework takes a
+vendor when a run with a real key passed on its starter (PE-733). Each run
+called a frontend tool, sent the tool result in a new run, called a backend
+tool, and asked a follow-up with page context. The runs used
+`gemini-3.8-flash` and `claude-sonnet-5`. The other vendors come in a later
+release:
+
+- Google on Microsoft Agent Framework (Python) and Strands Agents: their tool
+  loops drop the `thought_signature` that Gemini 3 returns with a tool call, so
+  Gemini refuses the next request.
+- CrewAI Flows: Gemini refuses it for the same reason, and its flow does not
+  return a backend tool result to the model with any vendor.
+- LlamaIndex and Microsoft Agent Framework (.NET): their starters send no page
+  context.
+- AG2, Deep Agents, MS Agent Harness (.NET) and Custom agent: no starter of
+  theirs ran.
+
+To use a held-back vendor for a new agent now, choose the built-in CopilotKit
+agent. An existing agent on a held-back vendor keeps it, and the plan says that
+this release has not proven that vendor on the framework.
 
 Read `status`:
 
@@ -2013,11 +2268,21 @@ copilotkit onboard credentials --model-key OPENAI_API_KEY \
 ```
 
 The step copies each key into that `.env` file. `copiedKeys` gives the outcome
-for each copy. A file that already holds another real value keeps it. If git
-tracks the file or does not ignore it, the key would be committed. Then the step
-writes nothing and asks the `env-file-exposed` question. If git cannot say
-whether it ignores the file, the step stops. A `--copy-to` file outside the
-repository is refused, because the run's backup cannot restore it.
+for each copy. A file that already holds another real value keeps it.
+
+- If git does not ignore an untracked file, the step adds the file's path,
+  anchored with `/`, to the `.gitignore` in the file's nearest existing folder.
+  Then it copies the key.
+- If the folder is in no git repository, the step copies the key. It also adds
+  the path to the `.gitignore` in the run root, for a later `git init`.
+- If git tracks the file, the key would be committed. Then the step writes
+  nothing and asks the `env-file-exposed` question. The step also asks that
+  question when it cannot add the ignore line, or when git still does not ignore
+  the file after the line is added. Then it removes the line again.
+- If git cannot be asked, and the folder can be in a repository, the step stops.
+
+`next` and `addedIgnoreLines` name each line the step added. A `--copy-to` file
+outside the repository is refused, because the run's backup cannot restore 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`:
@@ -2628,3 +2893,19 @@ settings and app references.
 model-choice inputs together before authentication. Cold installation,
 offline operation, and platform acceptance are not yet validated for a
 published candidate.
+
+### Claude Agent SDK imports
+
+Use `copilotkit import --source claude-agent-sdk-python --dry-run` or
+`--source claude-agent-sdk-typescript` for an explicitly selected native source.
+See the [SDK reader configuration and limits](../../libs/import-claude-sdk/README.md)
+for local transcripts, read-only custom SessionStore exports, language/version
+pins and original-session continuation requirements.
+
+### Claude Managed Agents imports
+
+Use `copilotkit import --source claude-managed-agents --managed-session-ids sesn_example --managed-user-id customer-id --dry-run`
+to preview a selected native session. Set `ANTHROPIC_API_KEY` for read access;
+`--managed-workspace-id` selects a source workspace when needed. See the
+[Managed Agents importer contract](../../libs/import-claude-managed/README.md)
+for discovery, saved-content limits, continuation companions and failure behavior.

package/cli-build-info.json

@@ -2,20 +2,20 @@
   "schemaVersion": 1,
   "package": {
     "name": "copilotkit",
-    "version": "4.28.0"
+    "version": "4.30.0"
   },
   "intelligence": {
-    "commit": "a033e00c2995392ce8ace961b4aba1acdf4705f5"
+    "commit": "775ac06c3cf4ce84d460ab9513e422440defec2c"
   },
   "copilotKit": {
-    "submittedInput": "c616389550105d5a96d74501f77c6921aa79ecee",
-    "commit": "c616389550105d5a96d74501f77c6921aa79ecee"
+    "submittedInput": "7e8e10bdd3",
+    "commit": "7e8e10bdd3f032fdda93a66aecea99e711aa37db"
   },
   "channel": "production",
   "triggeringActor": "BenTaylorDev",
   "workflow": {
-    "runId": "38464768008",
-    "runUrl": "https://github.com/CopilotKit/Intelligence/actions/runs/38464768008"
+    "runId": "39968806374",
+    "runUrl": "https://github.com/CopilotKit/Intelligence/actions/runs/39968806374"
   },
   "validationResult": "passed",
   "ag2": {
@@ -24,5 +24,5 @@
     "revision": "main",
     "pinned": false
   },
-  "builtAt": "2026-10-13T20:42:43Z"
+  "builtAt": "2026-10-23T14:22:28Z"
 }

package/exporters/claude-sdk/README.md

@@ -0,0 +1,93 @@
+# Claude Agent SDK history import
+
+This reader imports retained JSONL or a read-only custom SessionStore export into
+Intelligence's existing import/replay path. Python and TypeScript are separate
+sources. The current reader baselines are Python `0.2.166` and TypeScript
+`0.3.299`; focused synthetic tests do not establish released integration support.
+PNI-658 and PNI-659 own the required live content and continuation adapters.
+
+## Select a source
+
+Use an explicit project transcript directory; the CLI never scans your home
+Claude directory. Stop writers or copy the selected source to a stable snapshot.
+Do not copy unrelated sessions. Files over 64 MiB fail with a per-session error.
+
+```sh
+export CLAUDE_SDK_TRANSCRIPT_DIR=/path/to/selected/project-transcripts
+export CLAUDE_SDK_VERSION=0.2.166
+export CLAUDE_SDK_PROJECT_KEY=-original-working-directory
+export CLAUDE_SDK_SOURCE_ID=original-store
+export CLAUDE_SDK_AGENT_KEY=my-agent
+copilotkit import --source claude-agent-sdk-python --dry-run
+```
+
+For TypeScript use `claude-agent-sdk-typescript` and version `0.3.299`.
+`CLAUDE_SDK_END_USER_ID` explicitly assigns the original application's user ID.
+Otherwise choose the CLI's existing unrecoverable-user policy; it does not infer
+an end user from the person running the import. Supply the existing agent map,
+Intelligence API URL/key and confirmation flags to upload. Existing Skip/Replace,
+active-thread locks and transaction handling apply unchanged.
+
+## Custom SessionStore
+
+Use [exportSessionStore](src/store-export.ts) with the TypeScript store, or
+[export_session_store](python/export_session_store.py) with the Python store.
+These helpers call only `load`, optional session listing and optional subkey
+listing. Pass explicit session IDs when the store has no listing method. Export
+from stopped writers or a backend read snapshot: generic SessionStore has no
+cross-key transaction contract. No backend credentials go into the export.
+
+Serialize the helper result to a JSON file, unset `CLAUDE_SDK_TRANSCRIPT_DIR`, and
+set `CLAUDE_SDK_SESSION_STORE_EXPORT=/path/to/export.json`. The declared language,
+SDK version and project key must match configuration. This supports stores that
+return the native entries unchanged through these read methods; it does not
+assume a Redis, database or object-store layout. A missing entry fails export.
+
+The envelope is `claude-session-store-v1`, with `language`, `sdkVersion`,
+`projectKey`, and `sessions`. Each session has `sessionId`, ordered `entries`, and
+`subkeys` (`subpath` plus ordered `entries`). Python's helper translates only the
+store's snake_case selector names into this common envelope; native entries stay
+unchanged.
+
+## What replay preserves
+
+Root messages retain file order, native message and tool IDs, text, saved thinking,
+tool arguments/results and inline media bytes/MIME/filenames. URL media stays a
+structured attachment with its original URL and known MIME/name; extraction makes
+no network requests. URL availability is not guaranteed. Provider-file input
+remains unsupported by the SDK adapter; this importer does not add it. Unknown blocks remain
+visible JSON. Unknown root entries remain in native provenance. Child provenance retains only subpaths and entry counts; raw child transcripts are not copied into thread metadata. Empty or missing child transcripts produce visible import warnings.
+Saved children also become separate namespace histories, expandable on the parent
+conversation page. Recorded delegation links preserve nested children and native
+parent tool-call IDs; unavailable parent-call links stay explicitly unknown.
+Children do not become independent resumable threads or duplicate root messages. Native UI tool calls/results use shared replay conversion; this cannot
+recover middleware artifacts absent from the transcript.
+
+Historical `Tool call forwarded to client` results are marked as missing answers,
+not successful approvals. Import cannot reconstruct the real result from later
+user prose. Ordered successful state-tool updates merge shallowly. Without a
+saved complete base, provenance labels that recovered state `partial`; it is not
+published as the complete `stateSnapshot`. Native success-only state-tool results
+and transient system prompts do not prove that an initial state was saved.
+
+## Continuation boundary
+
+The native session UUID remains the imported thread ID. PNI-659's host binding
+resolver must recognize imported IDs, select the original working directory,
+SessionStore, tools and access, and fail if an imported session is unavailable.
+A missing imported session must not fall through to new-session creation.
+Saved `hook_deferred_tool` attachments recover one native approval only when
+they match an unresolved call on the intact current root chain. Its call ID,
+tool name and input must match. Later results clear it. Missing ancestry,
+conflicts or multiple pending deferrals are non-actionable. Frontend
+`mcp__ag_ui__` calls remain frontend tools; they are not native permissions.
+Historical in-process permission callbacks are not recoverable approvals.
+Import does not execute models/tools, repair native history, or sync subsequent
+activity sent directly to the SDK. Final product validation and release remain
+separate from these reader tests.
+
+## Sources
+
+- [Session persistence and SessionStore](https://code.claude.com/docs/en/agent-sdk/session-storage)
+- [Session continuation](https://code.claude.com/docs/en/agent-sdk/sessions)
+- [Python native history reader](https://github.com/anthropics/claude-agent-sdk-python/blob/main/src/claude_agent_sdk/_internal/sessions.py)

package/exporters/claude-sdk/export_session_store.py

@@ -0,0 +1,39 @@
+"""Read-only export for claude-agent-sdk 0.2.166 custom SessionStore objects.
+
+Call export_session_store(store, project_key, session_ids) from your application
+against quiesced storage or a consistent read snapshot. No query or writes run.
+"""
+
+
+async def export_session_store(store, project_key, session_ids=None):
+    """Preserve ordered native entries and opaque subkeys with Python key names."""
+    if session_ids is None:
+        listing = await store.list_sessions(project_key)
+        session_ids = [item["session_id"] for item in listing]
+    sessions = []
+    for session_id in dict.fromkeys(session_ids):
+        key = {"project_key": project_key, "session_id": session_id}
+        entries = await store.load(key)
+        if entries is None:
+            raise ValueError(f"Session {session_id} is missing")
+        subkeys = []
+        list_subkeys = getattr(store, "list_subkeys", None)
+        paths = []
+        if list_subkeys is not None:
+            try:
+                paths = await list_subkeys(key)
+            except NotImplementedError:
+                paths = []
+        for subpath in paths:
+            child = await store.load({**key, "subpath": subpath})
+            if child is None:
+                raise ValueError(f"Session subkey {subpath} is missing")
+            subkeys.append({"subpath": subpath, "entries": child})
+        sessions.append({"sessionId": session_id, "entries": entries, "subkeys": subkeys})
+    return {
+        "format": "claude-session-store-v1",
+        "language": "python",
+        "sdkVersion": "0.2.166",
+        "projectKey": project_key,
+        "sessions": sessions,
+    }