copilotkit 4.9.1 → 4.9.4

package/onboarding/prompts/subagent/prove-round-trip.md

@@ -1,27 +1,108 @@
 # Prove the complete round trip
 
-Use the proof steps and documentation URLs from the approved plan. Fetch every selected
-URL in one step before you start, rather than one after another.
-Do not use remembered CopilotKit instructions.
+Use the proof steps and documentation URLs from the approved plan. Follow the documentation
+policy the main coding agent gives you before you start.
 
-A fetch tool that refuses a URL, or fails to reach it, reports a limit of the tool and
-not a fact about the page. Retrieve the same URL a second way before you judge it. Run
-`curl -fsSL <url>`, or read the same page without the `.md` suffix. Report a
-documentation gap only after a second method also fails.
+Run the steps below in the order they appear. They are the proof. Do not design a
+different sequence of your own, and do not drop a step because an earlier one looked
+convincing. Step 6 has a web form and a React Native form: run the one that matches this
+journey's frontend, and run only that one.
 
-Read the port the developer's agent already serves from this project's own
-configuration. Do not assume a default, and do not start a second copy of an agent this
-project is already running. Before you bind any new server, check that the port is free
-and pick another one if it is not. Record every port you used.
+Record the result of every step as you go. A step with nothing recorded did not happen.
+Write each captured file to `.copilotkit/proof/` inside the project and name the path in
+the record. That directory holds regenerable evidence rather than application code. Where
+a browser or device tool writes to a location of its own, keep that location and record
+it instead.
 
-Start the agent and the selected frontend.
+Gather what you need in as few commands as possible. Combine independent reads into one
+command rather than running them one at a time. Split a command only when its result decides
+what you run next.
+
+## Step 1 -- Read what the proof needs
+
+Read all of this from the approved plan in one pass, before you start anything:
+
+- the exact request to send through the frontend, in the words the plan gave it,
+- the user-visible result that request has to produce,
+- the expected agent id,
+- where the project's own data lives, and which entities the answer has to name,
+- the start command for the agent and for the frontend, from the plan where it named
+  one and from the project's own scripts otherwise,
+- the runtime URL.
+
+Where the plan named no request, write one that produces the outcome the plan named, and
+record the request you wrote. Every later step uses these words unchanged, so that the
+browser, the device, and the grounding check all speak about one request.
+
+## Step 2 -- Start the agent and the frontend
+
+Read the port the developer's agent already serves from this project's own configuration.
+Do not assume a default, and do not start a second copy of an agent this project is
+already running. Before you bind any new server, check that the port is free and pick
+another one if it is not. Record every port you used.
+
+The table names what each frontend's own scaffolder writes, for recognizing a port in a
+started process's output. The project's configuration wins over the table.
+
+| Frontend     | Dev server the scaffolder writes |
+| ------------ | -------------------------------- |
+| Next.js      | `next dev`, port 3000            |
+| React SPA    | Vite, port 5173                  |
+| Vue 3        | Vite, port 5173                  |
+| Angular      | `ng serve`, port 4200            |
+| React Native | Metro, port 8081                 |
+
+Where this project's runtime runs as a process of its own, the frontend documentation
+puts it on port 8200. Use the runtime URL from step 1 rather than that number.
+
+Start each server in the background with the project's own script. Then wait for it to
+answer rather than for a fixed number of seconds:
+
+```bash
+ready=
+for _ in $(seq 90); do
+  curl -fs -o /dev/null "<url>" && ready=1 && break
+  sleep 1
+done
+[ "$ready" = 1 ] && echo "up" || echo "no answer from <url> after 90 seconds"
+```
+
+Read the loop's own last line rather than assuming it ended because the server answered.
+A server that never answered has written the reason to its own output, and reading that
+output is faster than starting it again.
 
 Leave the agent and frontend servers running after proof. Record each process ID and a
 safe command that stops that process. Record the frontend URL and the commands that start
 both servers again.
 
+## Step 3 -- Identify the process that answered
+
+Before you trust the agent, confirm that the process answering is the one in this
+repository. `verify` reports which agents the runtime declares and has nothing to compare
+them against, and `--round-trip` proves an agent answers under the declared id without
+proving which deployment did, so this comparison is yours. A health endpoint that returns
+success proves only that something listens on
+that port. An agent from earlier work often still holds it, and a stale process answers
+as though it were the new one. Ask the running agent which graph or agent id it serves
+and compare that with the id declared in this project.
+
+If they do not match, find out whose process it is before you signal anything.
+`lsof -ti :<port> -sTCP:LISTEN` gives the process id, and `lsof -a -p <pid> -d cwd` gives
+the directory it runs in. Stop it only when that directory is inside this project, and
+stop its children before the parent so nothing survives by reparenting. A holder outside
+this project belongs to other work: leave it running, report it, and bind to another port.
+Never stop a process because its command line matches a name. One `pkill` pattern reaches
+every project on the machine and takes down work that has nothing to do with this run.
+Never continue against a process you cannot identify, and never report a round trip proven
+by one.
+
+Address a local agent by host name rather than by an IP literal. Some local agents bind
+IPv6 only, so an IPv4 literal fails against the correct port.
+
+## Step 4 -- Check the wiring
+
 With both running, check the wiring in one command before you open a browser:
-`npx --yes copilotkit@4.9.1 verify --json`. Add `--runtime-url` when the runtime is not at
+`npx --yes copilotkit@4.9.4 verify --json`. Add `--runtime-url` when the runtime is not at
 `http://localhost:3000/api/copilotkit`. Read the individual checks rather than the summary
 alone: a check reported `undetermined` did not run, and that is not a pass. Fix anything
 that is not a pass before the browser, because a browser failure stacked on broken wiring
@@ -37,11 +118,12 @@ thread routes, which means saved Threads cannot load in a browser. The usual cau
 handler mounted `mode: "single-route"`: remove that option so the handler serves its full
 route set, and mount it at a catch-all route. If instead that check is `undetermined`
 because the runtime reports no thread-endpoint state, the runtime predates the field.
-Record that and move on — there is nothing to repair.
+Record that and move on -- there is nothing to repair.
+
+## Step 5 -- Prove that the agent runs
 
-Then prove that the agent actually runs, which is the gate for this node:
-`npx --yes copilotkit@4.9.1 verify --round-trip --json`. It sends one request through the
-runtime and reads the answer back from the thread, so it separates an agent that is
+Run `npx --yes copilotkit@4.9.4 verify --round-trip --json`. It sends one request through
+the runtime and reads the answer back from the thread, so it separates an agent that is
 configured from an agent that works. Use `--agent <id>` when the runtime declares more
 than one. If it reports `user-not-identified`, this project's `identifyUser` reads a
 session the CLI does not carry: pass what it reads with `--header "Name: value"` and run
@@ -49,64 +131,80 @@ it again, because an auth-gated app refusing an unauthenticated caller is that a
 working. Do not continue until this passes, and never report a round trip proven without
 it.
 
-Then send one real request through the frontend. Make sure that the request passes through
-CopilotKit and reaches the selected agent.
+## Step 6 -- Drive the surface
 
-For a recorded `both-oss` starting state: Compare the final round trip with the recorded
-OSS baseline. The same frontend request must still reach the same agent and produce the
-same kind of user-visible result. The runtime must now report `licenseStatus`, and the
-authenticated Intelligence checks must pass. Record both before and after evidence.
+Now send one real request through the running frontend, on this journey's own surface.
+Make sure that the request passes through CopilotKit and reaches the selected agent, and
+that the frontend receives working generative UI from the agent. This is the step that
+covers realtime delivery, the frontend provider being wired to this runtime, and a
+generative UI component actually rendering, and no command-line check reaches any of them.
+It is not optional polish: a run that skips it has proven the agent and not the journey,
+and the graph ends such a run as blocked rather than complete.
 
-Before you trust the agent, confirm that the process answering is the one in this
-repository. `verify` reports which agents the runtime declares and has nothing to compare
-them against, and `--round-trip` proves an agent answers under the declared id without
-proving which deployment did, so this comparison is yours. A health endpoint that returns success proves only that something listens on
-that port. An agent from earlier work often still holds it, and a stale process answers
-as though it were the new one. Ask the running agent which graph or agent id it serves
-and compare that with the id declared in this project.
+Use the surface control the main coding agent recorded for your environment. It either had
+one already or registered one before this step, so that finding is the answer and there is
+nothing here for you to go looking for. Do not add a browser driver or a device tool to this
+project: a devDependency and a browser download land in the diff and tax a repository that
+never asked for one, which is a different thing from the server registered against the
+coding agent. If nothing in your environment can drive the surface this journey needs, skip
+this step rather than installing one, and report the skip outcome named below.
 
-If they do not match, find out whose process it is before you signal anything.
-`lsof -ti :<port> -sTCP:LISTEN` gives the process id, and `lsof -a -p <pid> -d cwd` gives
-the directory it runs in. Stop it only when that directory is inside this project, and
-stop its children before the parent so nothing survives by reparenting. A holder outside
-this project belongs to other work: leave it running, report it, and bind to another port.
-Never stop a process because its command line matches a name. One `pkill` pattern reaches
-every project on the machine and takes down work that has nothing to do with this run.
-Never continue against a process you cannot identify, and never report a round trip proven
-by one.
-
-Address a local agent by host name rather than by an IP literal. Some local agents bind
-IPv6 only, so an IPv4 literal fails against the correct port.
-
-Drive the real UI on this journey's own surface, and make sure that the frontend receives
-working generative UI from the agent. This is the step that covers realtime delivery, the
-frontend provider being wired to this runtime, and a generative UI component actually
-rendering, and no command-line check reaches any of them. It is not optional polish: a run
-that skips it has proven the agent and not the journey, and the graph ends such a run as
-blocked rather than complete.
+Never report a result you did not see, on either surface.
 
-For a web frontend, that surface is a browser, and it also covers browser-origin CORS and
-CSP, which a CLI request never exercises. Use a browser MCP server already configured for
-the coding agent you are running as, the same way the CopilotKit documentation MCP server
-below is configured. Do not add a browser driver to this project: a devDependency and a
-browser download land in the diff and tax a repository that never asked for one. If nothing
-in your environment can drive a browser, skip this step rather than installing one.
+### Step 6a -- Web frontends: React SPA, Next.js, Angular, Vue 3
+
+The surface is a browser, and it also covers browser-origin CORS and CSP, which a CLI
+request never exercises. Drive it with the browser control step 6 named.
+
+1. Open the frontend URL from step 2 and wait for the page to finish loading.
+2. Take one page snapshot. Record whether the CopilotKit surface is on the page. A page
+   that renders without it is a wiring failure rather than a proof to retry.
+3. Read the browser console before you type anything, and record every error already
+   there. An error at this point belongs to page load rather than to the request.
+4. Enter the step 1 request into the CopilotKit input, in the words step 1 recorded, and
+   submit it.
+5. Wait for the assistant turn to finish rather than for a fixed number of seconds. The
+   turn is finished when the streamed text stops growing and the generative UI component
+   has rendered.
+6. Take one screenshot of the finished turn and record where you wrote it.
+7. Read the browser console a second time, and record every error that step 3 did not
+   already list. Those belong to the request.
+8. Read the network requests. Record every request the page made to the runtime endpoint
+   and the status each returned. An answer on the page with no successful request to this
+   runtime behind it came from something else, and that is a failed proof rather than a
+   passing one.
+9. Record one line for the finished turn: the time, the page URL, the element you read
+   the answer from, and what that element showed.
 
 Report exactly one of `performed`, `skipped-no-browser-tool`, or `failed` for a web
 frontend.
 
-For React Native, that surface is a device or emulator, and a browser cannot stand in for
-it. Run the app on a booted emulator, drive the same request, and capture the terminal
-state with `adb exec-out screencap -p`. Read `adb logcat` as well: a redbox is a runtime
-failure the terminal output never shows. If no device or emulator is available, skip this
-step rather than substituting a browser.
+### Step 6b -- React Native
+
+The surface is a device or emulator, and a browser cannot stand in for it.
+
+1. List the booted devices in one command: `adb devices -l`. With no booted device this
+   step is `skipped-no-device`. Do not substitute a browser.
+2. Build and install the app on the booted device with the project's own script, which
+   an Expo or React Native CLI project names in `package.json`.
+3. Clear the log buffer before the request: `adb logcat -c`.
+4. Open the CopilotKit surface in the running app and enter the step 1 request, in the
+   words step 1 recorded.
+5. Wait for the assistant turn to finish rather than for a fixed number of seconds.
+6. Capture the terminal state with
+   `adb exec-out screencap -p > .copilotkit/proof/surface.png`, and record that path.
+7. Read the log for the request with `adb logcat -d -t 500`. A redbox is a runtime failure
+   the terminal state never shows.
+8. Record one line for the finished turn: the time, the platform, the device id, the
+   screen you were on, and what that screen showed.
+
+An Android emulator reaches a runtime on the host machine at `10.0.2.2` rather than at
+`localhost`. A request that fails against the runtime with nothing in the runtime's own
+log is that, rather than a broken runtime.
 
 Report exactly one of `performed`, `skipped-no-device`, or `failed` for React Native.
 
-Never report a result you did not see, on either surface.
-
-Record the input, visible result, relevant process status, and evidence locations. Do not
-return secret values.
+## Step 7 -- Check the answer against the project's data
 
 Where the answer is meant to be about data the project holds, check it against that data.
 Read the entities the project holds -- the ids, names, or records the answer claims to
@@ -122,6 +220,16 @@ project's data never reaches the agent, the agent receives it and its instructio
 it, the page loads its data after the context was registered, or the run wired a different
 source than the page renders. Fix that cause, then prove again.
 
+## Step 8 -- Compare with the recorded OSS baseline
+
+Run this step only for a recorded `both-oss` starting state. Compare the final round trip
+with the recorded OSS baseline. The same frontend request must still reach the same agent
+and produce the same kind of user-visible result. The runtime must now report
+`licenseStatus`, and the authenticated Intelligence checks must pass. Record both before
+and after evidence.
+
+## Step 9 -- Set up the continued-development tools
+
 Fetch the continued-development guide from the main coding agent with the proof
 documentation. Try the continued-development tools after the application passes proof.
 Use it to install the project-scoped CopilotKit Skills.
@@ -131,9 +239,9 @@ Do not validate whether the Skills or MCP server installed correctly. Record the
 result for each attempt. Report each tool result separately. A tool error does not change
 the proof result.
 
-Gather what you need in as few commands as possible. Combine independent reads into one
-command rather than running them one at a time. Split a command only when its result decides
-what you run next.
+## Step 10 -- Return the result
 
 Return the proof or the exact failed step to the main coding agent, together with the
-surface-check outcome and which surface it speaks for. Stop after you return the result.
+input, the visible result, the relevant process status, the evidence locations, the
+surface-check outcome, and which surface that outcome speaks for. Do not return secret
+values. Stop after you return the result.

package/onboarding/prompts/unsupported/no-validated-path.md

@@ -18,13 +18,13 @@ Mark each step that the selected pages do not prove. Do not treat the documentat
 proof that the requested integration is unsupported.
 
 After the developer approves the best-effort plan, run
-`npx --yes copilotkit@4.9.1 onboard read fallback/best-effort`.
+`npx --yes copilotkit@4.9.4 onboard read fallback/best-effort`.
 
 Send one short report. Run the feedback command without another developer question. The
 CLI telemetry gate decides whether the report is sent.
 
 ```text
-npx --yes copilotkit@4.9.1 onboard feedback
+npx --yes copilotkit@4.9.4 onboard feedback
 ```
 
 Write the feedback message to the command's standard input, in at most four lines.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "copilotkit",
-  "version": "4.9.1",
+  "version": "4.9.4",
   "type": "module",
   "repository": {
     "type": "git",

package/release/release-tool.js

@@ -76,6 +76,9 @@ var agentCore = copilotKitStarter("examples/integrations/agentcore");
 var STARTER_SOURCE_CATALOG = {
   "langgraph-py": langGraphPython,
   "langgraph-js": copilotKitStarter("examples/integrations/langgraph-js"),
+  "langgraph-fastapi": copilotKitStarter(
+    "examples/integrations/langgraph-fastapi"
+  ),
   "claude-sdk-typescript": copilotKitStarter(
     "examples/integrations/claude-sdk-typescript"
   ),
@@ -14695,7 +14698,7 @@ import * as path4 from "node:path";
 
 // apps/cli/src/config.ts
 function getTemplateRef() {
-  return true ? "2ad03320fe1f0834b138113fffe791781e5b226e" : "main";
+  return true ? "f6f2dc4bb62b50d2f09384619f5b9e8fe7edde02" : "main";
 }
 
 // apps/cli/src/services/agentcore-config.ts
@@ -14897,6 +14900,7 @@ var AGENT_FRAMEWORKS = Object.keys(
 var FRAMEWORK_EMOJI = {
   "langgraph-py": "\u{1F99C}",
   "langgraph-js": "\u{1F99C}",
+  "langgraph-fastapi": "\u{1F99C}",
   "claude-sdk-typescript": "\u{1F506}",
   "claude-sdk-python": "\u{1F506}",
   flows: "\u{1F465}",
@@ -14927,6 +14931,10 @@ var FRAMEWORK_CHOICES = [
     label: `${FRAMEWORK_EMOJI["langgraph-js"]} LangGraph (JavaScript)`,
     value: "langgraph-js"
   },
+  {
+    label: `${FRAMEWORK_EMOJI["langgraph-fastapi"]} LangGraph (Python, FastAPI)`,
+    value: "langgraph-fastapi"
+  },
   {
     label: `${FRAMEWORK_EMOJI["claude-sdk-typescript"]} Claude Agent SDK (TypeScript)`,
     value: "claude-sdk-typescript"
@@ -15023,6 +15031,7 @@ var GOOGLE_ENV_KEY = {
 function standardTemplate(framework, template, successEmoji) {
   const pythonUvTemplates = /* @__PURE__ */ new Set([
     "langgraph-py",
+    "langgraph-fastapi",
     "claude-sdk-python",
     "flows",
     "llamaindex",
@@ -15060,6 +15069,11 @@ var FRAMEWORK_TEMPLATES = {
     TEMPLATE_REPOS["langgraph-js"],
     `\u{1FA81}\u{1F91D}${FRAMEWORK_EMOJI["langgraph-js"]}`
   ),
+  "langgraph-fastapi": standardTemplate(
+    "langgraph-fastapi",
+    TEMPLATE_REPOS["langgraph-fastapi"],
+    `\u{1FA81}\u{1F91D}${FRAMEWORK_EMOJI["langgraph-fastapi"]}`
+  ),
   "claude-sdk-typescript": {
     ...standardTemplate(
       "claude-sdk-typescript",