chore: merge main, resolve conflicts on built-in-agent slug

Author: AlemTuzlak

.github/workflows/ghcr_unlinked_packages.yml

@@ -0,0 +1,172 @@
+# Daily audit for GHCR container packages that are unlinked from a source
+# repository (`repository: null` on the GHCR API).
+#
+# WHY THIS EXISTS
+# ---------------
+# When a GHCR container package is not linked to a repository, workflow
+# builds in `CopilotKit/CopilotKit` get `403 Forbidden` on push to GHCR —
+# the workflow's `GITHUB_TOKEN` only has package-write permissions when
+# the package is linked to the actor's repo. We hit this twice in quick
+# succession (`showcase-ops` caught manually after a failed deploy, and
+# `showcase-pocketbase` caught by a preemptive scan). There is NO GitHub
+# API to programmatically link a package to a repo — it is UI-only — so
+# the only way to prevent future surprises is detect drift early via a
+# scheduled audit + Slack alert.
+#
+# This workflow is the operationalization of the lesson captured in
+# `feedback_ghcr_new_package_403.md`.
+#
+# REQUIRED SECRETS
+# ----------------
+# - ORG_READ_PACKAGES_PAT: a fine-grained PAT with `read:packages` scope,
+#   org-scoped to `CopilotKit`. The default `secrets.GITHUB_TOKEN` does
+#   NOT have `read:packages` for the org and cannot list org packages.
+# - SLACK_WEBHOOK_GHCR_DRIFT: a CopilotKit-internal Slack incoming-webhook
+#   URL. Posts to whichever channel the webhook is bound to (intended:
+#   an internal alerts channel).
+#
+# If `ORG_READ_PACKAGES_PAT` is unset the workflow fails loudly — drift
+# detection silently disabled is worse than no workflow at all.
+# If `SLACK_WEBHOOK_GHCR_DRIFT` is unset the workflow logs a warning
+# (the audit still runs) so a missing webhook does not mask drift.
+#
+# EXIT CODES
+# ----------
+# This workflow exits 0 in all non-error cases (including when drift is
+# present). The Slack message IS the alert; failing the workflow on
+# drift would create noisy red CI checks on a schedule.
+
+name: GHCR unlinked-package audit
+
+on:
+  schedule:
+    # Daily at 14:00 UTC (07:00 PT / 10:00 ET) — low-traffic window,
+    # well before the US workday's deploy activity.
+    - cron: "0 14 * * *"
+  workflow_dispatch: {}
+
+permissions:
+  contents: read
+
+jobs:
+  audit:
+    name: Audit org container packages for unlinked repos
+    # Hoist the Slack webhook into an env var so step-level `if:`
+    # expressions can reference it — `secrets.*` is not a valid
+    # named-value inside `if:` and causes a workflow startup failure.
+    env:
+      SLACK_WEBHOOK: ${{ secrets.SLACK_WEBHOOK_GHCR_DRIFT }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Verify ORG_READ_PACKAGES_PAT is set
+        env:
+          PAT: ${{ secrets.ORG_READ_PACKAGES_PAT }}
+        run: |
+          if [ -z "$PAT" ]; then
+            echo "::error::ORG_READ_PACKAGES_PAT is not set. This workflow requires a fine-grained PAT with read:packages scope, org-scoped to CopilotKit. See the workflow header comment in .github/workflows/ghcr_unlinked_packages.yml for setup."
+            exit 1
+          fi
+          echo "ORG_READ_PACKAGES_PAT present."
+
+      - name: List org container packages and identify unlinked
+        id: audit
+        env:
+          GH_TOKEN: ${{ secrets.ORG_READ_PACKAGES_PAT }}
+        run: |
+          set -euo pipefail
+
+          # Page through all container packages in the CopilotKit org.
+          # `--paginate` follows Link headers; per_page=100 minimizes
+          # request count. `gh api` returns one JSON array per page;
+          # `--slurp` is unnecessary because gh concatenates pages into
+          # a single stream when called with `--paginate` on an array
+          # endpoint.
+          all_packages_json="$(gh api \
+            --paginate \
+            -H "Accept: application/vnd.github+json" \
+            "/orgs/CopilotKit/packages?package_type=container&per_page=100")"
+
+          total="$(echo "$all_packages_json" | jq 'length')"
+          echo "Total container packages in CopilotKit org: $total"
+
+          # Filter for packages where repository is null. Emit a compact
+          # JSON array of {name, visibility} objects for downstream use.
+          unlinked_json="$(echo "$all_packages_json" \
+            | jq -c '[.[] | select(.repository == null) | {name: .name, visibility: .visibility}]')"
+
+          unlinked_count="$(echo "$unlinked_json" | jq 'length')"
+          echo "Unlinked container packages: $unlinked_count"
+
+          # Emit outputs for the next step. Use the multiline-output
+          # delimiter form for the JSON array so jq output with embedded
+          # special chars survives intact.
+          {
+            echo "unlinked_count=$unlinked_count"
+            echo "unlinked_json<<EOF"
+            echo "$unlinked_json"
+            echo "EOF"
+          } >> "$GITHUB_OUTPUT"
+
+          if [ "$unlinked_count" = "0" ]; then
+            echo "::notice::No GHCR drift — all CopilotKit org container packages are linked to a repository."
+          else
+            echo "::warning::Detected $unlinked_count unlinked container package(s):"
+            echo "$unlinked_json" | jq -r '.[] | "  - \(.name) (\(.visibility))"'
+          fi
+
+      - name: Build Slack payload
+        id: payload
+        if: steps.audit.outputs.unlinked_count != '0'
+        env:
+          UNLINKED_JSON: ${{ steps.audit.outputs.unlinked_json }}
+          UNLINKED_COUNT: ${{ steps.audit.outputs.unlinked_count }}
+          RUN_URL: https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}
+        run: |
+          set -euo pipefail
+
+          # Build a single `text` field with mrkdwn — keeps the payload
+          # compatible with both incoming-webhooks and channel webhooks.
+          # Each unlinked package gets a deep link to its Actions-access
+          # settings page, where the UI fix lives.
+          lines="$(echo "$UNLINKED_JSON" | jq -r '.[] | "• <https://github.com/orgs/CopilotKit/packages/container/\(.name)/settings|\(.name)> (\(.visibility))"')"
+
+          # Build message via printf — avoids heredoc indentation
+          # gotchas (closing delimiter must be column-0, which confuses
+          # YAML linters on `run: |` blocks). mrkdwn renders *bold*,
+          # _italic_, and <url|label> links.
+          nl=$'\n'
+          message=":warning: *GHCR drift detected* — ${UNLINKED_COUNT} container package(s) in the \`CopilotKit\` org are unlinked from a source repository.${nl}${nl}"
+          message="${message}${lines}${nl}${nl}"
+          message="${message}*UI fix (per package):* open the settings link above → *Manage Actions access* → *Add Repository* → \`CopilotKit/CopilotKit\` → *Write*.${nl}${nl}"
+          message="${message}_This drift breaks future workflow builds with \`403 Forbidden\` on push to GHCR. <${RUN_URL}|View audit run>_"
+
+          # Emit as a multiline output so the next step can consume it
+          # without re-quoting through a shell.
+          {
+            echo "text<<EOF"
+            echo "$message"
+            echo "EOF"
+          } >> "$GITHUB_OUTPUT"
+
+      - name: Notify Slack (drift detected)
+        if: steps.audit.outputs.unlinked_count != '0' && env.SLACK_WEBHOOK != ''
+        uses: slackapi/slack-github-action@v2.1.0
+        with:
+          webhook: ${{ secrets.SLACK_WEBHOOK_GHCR_DRIFT }}
+          webhook-type: incoming-webhook
+          # Wrap the dynamic message via toJSON so quotes/newlines/
+          # backslashes inside package names or visibility values are
+          # safely JSON-encoded instead of breaking the payload.
+          payload: |
+            { "text": ${{ toJSON(steps.payload.outputs.text) }} }
+
+      - name: Log (no Slack — webhook unset)
+        if: steps.audit.outputs.unlinked_count != '0' && env.SLACK_WEBHOOK == ''
+        run: |
+          echo "::warning::Drift detected but SLACK_WEBHOOK_GHCR_DRIFT is not set; no Slack notification sent. See run logs above for the unlinked package list."
+
+      - name: Log (no drift)
+        if: steps.audit.outputs.unlinked_count == '0'
+        run: |
+          echo "No drift — exiting 0."

.github/workflows/showcase_deploy.yml

@@ -53,6 +53,7 @@ on:
           - shell-dojo
           - shell-dashboard
           - shell-docs
+          - showcase-ops
 
 concurrency:
   # Key on `event_name + ref` so push events and manual workflow_dispatch
@@ -179,6 +180,11 @@ jobs:
               - 'showcase/shared/**'
               - 'showcase/scripts/**'
               - 'showcase/packages/*/manifest.yaml'
+            showcase_ops:
+              - 'showcase/ops/**'
+              - 'showcase/shared/**'
+              - 'showcase/scripts/**'
+              - 'showcase/packages/*/manifest.yaml'
 
       - name: Build service matrix
         id: build-matrix
@@ -228,8 +234,9 @@ jobs:
             {"dispatch_name":"starter-spring-ai","filter_key":"starter_spring_ai","context":"showcase/starters/spring-ai","image":"showcase-starter-spring-ai","railway_id":"3559ece3-7ba3-41ac-b24c-1f780133ec58","timeout":15,"lfs":false,"build_args":"","dockerfile":"","health_path":"/api/health"},
             {"dispatch_name":"starter-strands","filter_key":"starter_strands","context":"showcase/starters/strands","image":"showcase-starter-strands","railway_id":"06db2bb8-e15d-4c6a-97ad-e14777c92d9f","timeout":15,"lfs":false,"build_args":"","dockerfile":"","health_path":"/api/health"},
             {"dispatch_name":"shell-dojo","filter_key":"shell_dojo","context":".","image":"showcase-shell-dojo","railway_id":"7ad1ece7-2228-49cd-8a78-bddf30322907","timeout":10,"lfs":false,"build_args":"","dockerfile":"showcase/shell-dojo/Dockerfile","health_path":"/"},
-            {"dispatch_name":"shell-dashboard","filter_key":"shell_dashboard","context":".","image":"showcase-shell-dashboard","railway_id":"4d5dfd74-be61-40b2-8564-b53b7dd4c15b","timeout":10,"lfs":true,"build_args_sha":"${{ github.sha }}","build_args_branch":"${{ github.ref_name }}","build_args_pb_url":"https://showcase-pocketbase-production.up.railway.app","build_args_shell_url":"https://showcase.copilotkit.ai","dockerfile":"showcase/shell-dashboard/Dockerfile","health_path":"/"},
-            {"dispatch_name":"shell-docs","filter_key":"shell_docs","context":".","image":"showcase-shell-docs","railway_id":"7badfb8d-4228-414c-9145-b4026803714f","timeout":10,"lfs":true,"build_args_sha":"${{ github.sha }}","build_args_branch":"${{ github.ref_name }}","dockerfile":"showcase/shell-docs/Dockerfile","health_path":"/"}
+            {"dispatch_name":"shell-dashboard","filter_key":"shell_dashboard","context":".","image":"showcase-shell-dashboard","railway_id":"4d5dfd74-be61-40b2-8564-b53b7dd4c15b","timeout":10,"lfs":true,"build_args_sha":"${{ github.sha }}","build_args_branch":"${{ github.ref_name }}","build_args_pb_url":"https://showcase-pocketbase-production.up.railway.app","build_args_shell_url":"https://showcase.copilotkit.ai","build_args_ops_url":"https://showcase-ops-production.up.railway.app","dockerfile":"showcase/shell-dashboard/Dockerfile","health_path":"/"},
+            {"dispatch_name":"shell-docs","filter_key":"shell_docs","context":".","image":"showcase-shell-docs","railway_id":"7badfb8d-4228-414c-9145-b4026803714f","timeout":10,"lfs":true,"build_args_sha":"${{ github.sha }}","build_args_branch":"${{ github.ref_name }}","dockerfile":"showcase/shell-docs/Dockerfile","health_path":"/"},
+            {"dispatch_name":"showcase-ops","filter_key":"showcase_ops","context":".","image":"showcase-ops","railway_id":"3a14bfed-0537-4d71-897b-7c593dca161d","timeout":20,"lfs":false,"build_args":"","dockerfile":"showcase/ops/Dockerfile","health_path":"/health"}
           ]'
 
           DISPATCH="${{ github.event.inputs.service }}"
@@ -349,6 +356,11 @@ jobs:
           if [ -n "${{ matrix.service.build_args_shell_url }}" ]; then
             ARGS="${ARGS:+${ARGS}$'\n'}NEXT_PUBLIC_SHELL_URL=${{ matrix.service.build_args_shell_url }}"
           fi
+          if [ -n "${{ matrix.service.build_args_ops_url }}" ]; then
+            # OPS_BASE_URL is required at build time by shell-dashboard's
+            # next.config.ts rewrites() — without it `next build` aborts.
+            ARGS="${ARGS:+${ARGS}$'\n'}OPS_BASE_URL=${{ matrix.service.build_args_ops_url }}"
+          fi
           # Use delimiter to safely pass multiline value
           echo "args<<BUILDARGS_EOF" >> $GITHUB_OUTPUT
           echo "$ARGS" >> $GITHUB_OUTPUT

.github/workflows/showcase_validate.yml

@@ -119,8 +119,15 @@ jobs:
           found=0
           for pkg_dir in showcase/packages/*/; do
             [ -d "$pkg_dir" ] || continue
-            found=$((found + 1))
             pkg=$(basename "$pkg_dir")
+            # Skip manifest-only packages (no src/ directory) — these are
+            # virtual/meta integrations (e.g. built-in-agent) that carry no
+            # source code or demos and therefore have no e2e specs to enforce.
+            if [ ! -d "${pkg_dir}src" ]; then
+              echo "skip: $pkg (manifest-only, no src/)"
+              continue
+            fi
+            found=$((found + 1))
             e2e_dir="${pkg_dir}tests/e2e/"
             if [ ! -d "$e2e_dir" ]; then
               echo "::error file=$pkg_dir::Package '$pkg' is missing tests/e2e/ directory (required for baseline e2e coverage)"

.github/workflows/static_quality.yml

@@ -74,7 +74,7 @@ jobs:
           git diff --name-only --diff-filter=ACMR "origin/$base_ref"...HEAD -- \
             '*.js' '*.jsx' '*.ts' '*.tsx' '*.mjs' '*.cjs' \
             '*.json' '*.jsonc' '*.json5' \
-            '*.md' '*.mdx' \
+            '*.md' \
             '*.css' '*.yml' '*.yaml' '*.html' '*.vue' \
             > .pr-format-files.txt
           : > .pr-format-files.existing.txt

docs/content/docs/integrations/langgraph/agent-app-context.mdx

@@ -84,17 +84,17 @@ This context can then be shared with your LangChain agent.
                     <Tab value="TypeScript">
                         ```typescript title="agent-js/src/agent.ts"
                         // ...
-                        import { Annotation } from "@langchain/langgraph";
-                        import { CopilotKitStateAnnotation } from "@copilotkit/sdk-js/langgraph";
+                        import { StateSchema } from "@langchain/langgraph";
+                        import { CopilotKitStateSchema } from "@copilotkit/sdk-js/langgraph";
                         // ...
 
                         // This is the state of the agent.
                         // It inherits from the CopilotKitState properties from CopilotKit.
-                        export const AgentStateAnnotation = Annotation.Root({
+                        export const AgentStateSchema = new StateSchema({
                           // ... Your defined state properties
-                          ...CopilotKitStateAnnotation.spec,
+                          ...CopilotKitStateSchema.fields,
                         });
-                        export type AgentState = typeof AgentStateAnnotation.State;
+                        export type AgentState = typeof AgentStateSchema.State;
                         ```
                     </Tab>
                 </Tabs>
@@ -148,11 +148,11 @@ This context can then be shared with your LangChain agent.
                         import { ChatOpenAI } from "@langchain/openai";
 
                         // add the agent state definition from the previous step
-                        export const AgentStateAnnotation = Annotation.Root({
+                        export const AgentStateSchema = new StateSchema({
                           // ... Your defined state properties
-                          ...CopilotKitStateAnnotation.spec,
+                          ...CopilotKitStateSchema.fields,
                         });
-                        export type AgentState = typeof AgentStateAnnotation.State;
+                        export type AgentState = typeof AgentStateSchema.State;
 
                         async function chat_node(state: AgentState, config: RunnableConfig) {
                           // Extract the colleagues from CopilotKit context

docs/content/docs/integrations/langgraph/configurable.mdx

@@ -107,17 +107,18 @@ Now you can simply pull the values from the provided config argument in any agen
         </Tab>
         <Tab value="TypeScript">
             ```typescript
-            import { Annotation } from "@langchain/langgraph";
+            import { StateSchema } from "@langchain/langgraph";
+            import { z } from "zod";
 
             // define which properties will be allowed in the configuration
-            export const ConfigSchemaAnnotation = Annotation.Root({
-              authToken: Annotation<string>
+            export const ConfigSchema = new StateSchema({
+              authToken: z.string()
             })
 
             // ...add all necessary graph nodes
 
             // when defining the state graph, apply the config schema
-            const workflow = new StateGraph(AgentStateAnnotation, ConfigSchemaAnnotation)
+            const workflow = new StateGraph(AgentStateSchema, ConfigSchema)
             ```
         </Tab>
     </Tabs>

docs/content/docs/integrations/langgraph/frontend-tools.mdx

@@ -96,14 +96,15 @@ Use frontend tools when you need your agent to interact with client-side primiti
             </Tab>
             <Tab value="TypeScript">
                 ```typescript title="agent-js/src/agent.ts"
-                import { Annotation } from "@langchain/langgraph";
-                import { CopilotKitStateAnnotation } from "@copilotkit/sdk-js/langgraph"; // [!code highlight]
+                import { StateSchema } from "@langchain/langgraph";
+                import { CopilotKitStateSchema } from "@copilotkit/sdk-js/langgraph"; // [!code highlight]
+                import { z } from "zod";
 
-                export const YourAgentStateAnnotation = Annotation.Root({
-                    yourAdditionalProperty: Annotation<string>,
-                    ...CopilotKitStateAnnotation.spec, // [!code highlight]
+                export const YourAgentStateSchema = new StateSchema({
+                    yourAdditionalProperty: z.string(),
+                    ...CopilotKitStateSchema.fields, // [!code highlight]
                 });
-                export type YourAgentState = typeof YourAgentStateAnnotation.State;
+                export type YourAgentState = typeof YourAgentStateSchema.State;
                 ```
             </Tab>
         </Tabs>

docs/content/docs/integrations/langgraph/generative-ui/state-rendering.mdx

@@ -51,14 +51,15 @@ Use state rendering when you want to:
         </Tab>
         <Tab value="TypeScript">
           ```typescript title="agent-js/src/agent.ts"
-          import { Annotation } from "@langchain/langgraph";
-          import { CopilotKitStateAnnotation } from "@copilotkit/sdk-js/langgraph";
+          import { StateSchema } from "@langchain/langgraph";
+          import { CopilotKitStateSchema } from "@copilotkit/sdk-js/langgraph";
+          import { z } from "zod";
 
-          export const AgentStateAnnotation = Annotation.Root({
-            searches: Annotation<{ query: string; done: boolean }[]>,
-            ...CopilotKitStateAnnotation.spec,
+          export const AgentStateSchema = new StateSchema({
+            searches: z.array(z.object({ query: z.string(), done: z.boolean() })).default(() => []),
+            ...CopilotKitStateSchema.fields,
           });
-          export type AgentState = typeof AgentStateAnnotation.State;
+          export type AgentState = typeof AgentStateSchema.State;
           ```
         </Tab>
     </Tabs>

docs/content/docs/integrations/langgraph/generative-ui/your-components/display-only.mdx

@@ -92,13 +92,13 @@ For components that need user interaction, see [Interactive](/langgraph/generati
       </Tab>
       <Tab value="TypeScript">
         ```typescript title="agent-js/src/agent.ts"
-        import { Annotation } from "@langchain/langgraph";
-        import { CopilotKitStateAnnotation } from "@copilotkit/sdk-js/langgraph"; // [!code highlight]
+        import { StateSchema } from "@langchain/langgraph";
+        import { CopilotKitStateSchema } from "@copilotkit/sdk-js/langgraph"; // [!code highlight]
 
-        export const AgentStateAnnotation = Annotation.Root({
-          ...CopilotKitStateAnnotation.spec, // [!code highlight]
+        export const AgentStateSchema = new StateSchema({
+          ...CopilotKitStateSchema.fields, // [!code highlight]
         });
-        export type AgentState = typeof AgentStateAnnotation.State;
+        export type AgentState = typeof AgentStateSchema.State;
         ```
       </Tab>
     </Tabs>