Assign the openbot Learning container automatically (CopilotKit#774)

Author: davidmckayv

.env.example

@@ -144,10 +144,14 @@ COPILOTKIT_LICENSE_TOKEN=
 # Learning defaults on. Fresh managed setup: login, project select, then bun scripts/setup-learning.ts.
 # The helper creates/reuses openbot and writes the verified key and container; custom targets stay.
 # Fresh self-hosted setup: set its API URL, install Chrome/Edge, then run the same helper to sign in.
-# Existing key-only setup: create a container in that project before assigning its ID below.
+# With nothing saved in Admin and no container below, the server assigns the key's project's openbot
+# container by itself once it exists. The key cannot create it: run the helper (it keeps an existing
+# key) or create it in Intelligence. scripts/start.sh runs that check on every start, non-interactively.
 # Admin → Automatic Learning can enable/disable, override per Bot, and save settings in the DB.
 # Saved settings take precedence, including off. Without an assigned container, collection and
 # delivery stay inactive; OpenBot still starts and chats.
+# false or 0 stops the automatic openbot assignment. A container named below also stops it.
+# OPENBOT_LEARNING_AUTO_ASSIGN=false
 # Project credentials remain server-side; review and publish skills in the Intelligence UI.
 # CPK_INTELLIGENCE_LEARNING_CONTAINER_ID=support-learning
 # Optional opaque published revision ID; omit to follow latest.

CHANGELOG.md

@@ -8,6 +8,18 @@ Newest first. `Unreleased` is what is on `main` and not yet tagged.
 
 ## Unreleased
 
+### Automatic Learning assigns its container without a trip to Admin
+
+Learning was on by default but collected nothing until somebody assigned a container. Now, when
+nothing is saved under Admin → Automatic Learning and `CPK_INTELLIGENCE_LEARNING_CONTAINER_ID` is
+not set, the server assigns its Intelligence project's `openbot` container as the default as soon as
+that container exists, records it in the audit log, and the Admin page says so. A saved setting,
+including off, is never changed. The runtime key cannot create a container, so
+`bun scripts/setup-learning.ts` now creates `openbot` in an existing key's project instead of
+refusing, and `scripts/start.sh` runs that check on every start without a browser or prompt. Set
+`OPENBOT_LEARNING_AUTO_ASSIGN=false` (Helm: `config.learning.autoAssign: false`) to keep the old
+behaviour.
+
 ### Memory lives in CopilotKit Intelligence
 
 A deployment entitled to Intelligence memory now keeps its people's memories there: Intelligence holds

README.md

@@ -93,14 +93,16 @@ A Bot is any endpoint speaking [AG-UI](https://github.com/ag-ui-protocol/ag-ui),
 
    The helper provisions the selected project's runtime key, creates or reuses its
    `openbot` Learning container, then writes both settings to `.env`. It preserves
-   custom container assignments and refuses to replace an existing OpenBot key.
+   custom container assignments and never replaces an existing OpenBot key; with one
+   set, it only creates `openbot` in that key's project if it is missing.
    For fresh self-hosted setup, set `INTELLIGENCE_API_URL` to that deployment's
    HTTPS API origin (or `http://localhost` for a local one) and run the helper
    without the two `npx` commands. It opens an isolated Chrome or Edge window for
    your usual sign-in and project choice; install either browser first. It writes
    the API URL, the key and the container, not `INTELLIGENCE_GATEWAY_WS_URL`, so
-   set that one to the same deployment yourself. Existing key-only setups can assign a container
-   through [Admin → Automatic Learning](docs/automatic-learning.md).
+   set that one to the same deployment yourself. Once `openbot` exists, the server assigns it
+   as the default by itself unless [Admin → Automatic Learning](docs/automatic-learning.md)
+   has a saved setting.
    Managed Intelligence needs no separate licence token.
 
 3. Fill the remaining required values:

app/src/lib/learning/queries.ts

@@ -1,6 +1,7 @@
 import { queryOptions } from "@tanstack/react-query";
 import { client } from "@/lib/client";
 import type {
+  LearningAutoAssignState,
   LearningDeliveryStatus,
   LearningOverview,
   LearningSettings,
@@ -9,6 +10,7 @@ import type {
 export const learningKeys = {
   all: ["learning"] as const,
   settings: ["learning", "settings"] as const,
+  automatic: ["learning", "automatic"] as const,
 };
 export function learningSettingsQueryOptions() {
   return queryOptions({
@@ -19,6 +21,19 @@ export function learningSettingsQueryOptions() {
       }),
   });
 }
+/** Why no container was assigned automatically, or `null` when the server has nothing to say. */
+export function learningAutomaticQueryOptions() {
+  return queryOptions({
+    queryKey: learningKeys.automatic,
+    retry: false,
+    queryFn: async (): Promise<LearningAutoAssignState | null> =>
+      (await client<LearningAutoAssignState | undefined>(
+        "/api/admin/learning/settings",
+        "automatic",
+        { fallback: "Learning settings could not be loaded." },
+      )) ?? null,
+  });
+}
 export function learningOverviewQueryOptions(agentId?: string) {
   return queryOptions({
     queryKey: ["learning", "overview", agentId],

app/src/routes/_authed/admin/learning.tsx

@@ -6,13 +6,15 @@ import { Button } from "@/components/ui/button";
 import { Input } from "@/components/ui/input";
 import { agentListQueryOptions } from "@/lib/agents/queries";
 import {
+  learningAutomaticQueryOptions,
   learningDeliveryQueryOptions,
   learningKeys,
   learningOverviewQueryOptions,
   learningSettingsQueryOptions,
   saveLearningSettings,
 } from "@/lib/learning/queries";
 import type {
+  LearningAutoAssignState,
   LearningSettings,
   LearningTarget,
 } from "../../../../../shared/learning";
@@ -22,6 +24,26 @@ export const Route = createFileRoute("/_authed/admin/learning")({
 });
 const selectClass = "w-full rounded-md border bg-background px-3 py-2 text-sm";
 
+/** What automatic assignment found, in words, or nothing when there is nothing to say. */
+function automaticMessage(
+  automatic: LearningAutoAssignState | null | undefined,
+  settings: LearningSettings,
+): string | undefined {
+  if (!automatic) return undefined;
+  if (
+    automatic.state === "assigned" &&
+    settings.defaultTarget?.containerId === automatic.containerId
+  )
+    return `OpenBot assigned this Intelligence project's "${automatic.containerId}" container automatically. Change it here at any time.`;
+  if (automatic.state === "absent")
+    return `This Intelligence project has no "${automatic.containerId}" Learning container yet, so nothing is collected. Create a container with that ID in Intelligence, or run bun scripts/setup-learning.ts, and OpenBot assigns it automatically.`;
+  if (automatic.state === "not_entitled")
+    return "This Intelligence project's plan does not include Learning, so no container was assigned.";
+  if (automatic.state === "unavailable")
+    return "OpenBot could not ask Intelligence for this project's Learning container. It tries again.";
+  return undefined;
+}
+
 function TargetFields({
   target,
   onChange,
@@ -76,6 +98,7 @@ function TargetFields({
 export function LearningPage() {
   const queryClient = useQueryClient();
   const settingsQuery = useQuery(learningSettingsQueryOptions());
+  const automatic = useQuery(learningAutomaticQueryOptions());
   const agents = useQuery(agentListQueryOptions());
   const hiddenAgents = useQuery(agentListQueryOptions(true));
   const roster = [...(agents.data ?? []), ...(hiddenAgents.data ?? [])];
@@ -87,6 +110,11 @@ export function LearningPage() {
   );
   const delivery = useQuery(learningDeliveryQueryOptions(selected));
   const settings = draft ?? settingsQuery.data;
+  // About what is saved, so it steps aside while an edit is in progress.
+  const automaticNote =
+    settingsQuery.data && !draft
+      ? automaticMessage(automatic.data, settingsQuery.data)
+      : undefined;
   const save = useMutation({
     mutationFn: saveLearningSettings,
     onSuccess: async (next) => {
@@ -118,7 +146,7 @@ export function LearningPage() {
     >
       <PageSection
         title="Participation"
-        description="Changes to container assignments apply to new threads. Existing threads keep their first assignment. Containers must already exist in the same Intelligence project."
+        description="Changes to container assignments apply to new threads. Existing threads keep their first assignment. Containers must already exist in the same Intelligence project. Until anything is saved here, OpenBot assigns that project's openbot container automatically."
       >
         {settingsQuery.isPending && (
           <p role="status">Loading Learning settings…</p>
@@ -153,6 +181,11 @@ export function LearningPage() {
                 change({ ...settings, defaultTarget })
               }
             />
+            {automaticNote && (
+              <p role="status" className="text-sm">
+                {automaticNote}
+              </p>
+            )}
             <p className="text-muted-foreground text-sm">
               An empty default leaves unmapped Bots out. IDs use 1–64 lowercase
               letters, numbers, and single hyphens. Leave revision empty to

app/tests/learning-admin.test.tsx

@@ -130,3 +130,60 @@ test("active and hidden Bots both have participation controls", async () => {
   await view.findByLabelText("hidden-bot participation");
   expect(view.queryByLabelText("active-bot participation")).not.toBeNull();
 });
+
+function serve(body: unknown) {
+  global.fetch = Object.assign(
+    async (input: RequestInfo | URL) => {
+      const path = String(input);
+      if (path.endsWith("/settings")) return Response.json(body);
+      if (path.includes("/api/agents")) return Response.json({ agents: [] });
+      return Response.json({ error: "unavailable" }, { status: 502 });
+    },
+    { preconnect: originalFetch.preconnect },
+  );
+}
+
+test.each([
+  [
+    { enabled: true, defaultTarget: null, agents: {} },
+    { state: "absent", containerId: "openbot" },
+    'This Intelligence project has no "openbot" Learning container yet',
+  ],
+  [
+    { enabled: true, defaultTarget: { containerId: "openbot" }, agents: {} },
+    { state: "assigned", containerId: "openbot" },
+    'OpenBot assigned this Intelligence project\'s "openbot" container automatically',
+  ],
+  [
+    { enabled: true, defaultTarget: null, agents: {} },
+    { state: "not_entitled" },
+    "plan does not include Learning",
+  ],
+] as const)(
+  "the page says what automatic assignment found (%#)",
+  async (settings, automatic, expected) => {
+    serve({ settings, automatic });
+    const view = page();
+    await view.findByText(expected, { exact: false });
+  },
+);
+
+test("a deployment that chose its own container hears nothing about automatic assignment", async () => {
+  serve({
+    settings: {
+      enabled: true,
+      defaultTarget: { containerId: "support" },
+      agents: {},
+    },
+    automatic: { state: "saved" },
+  });
+  const view = page();
+  await view.findByLabelText("Default container ID");
+  await waitFor(() =>
+    expect(view.queryByText("Loading Learning settings…")).toBeNull(),
+  );
+  expect(view.queryByText("OpenBot assigned", { exact: false })).toBeNull();
+  expect(
+    view.queryByText("Learning container yet", { exact: false }),
+  ).toBeNull();
+});

charts/openbot/README.md

@@ -344,7 +344,11 @@ nobody can talk to.
 ## Automatic Learning
 
 Learning is on by default, and it needs a container in the Intelligence project before it collects or
-delivers anything. `config.learning.containerId` sets the initial default container
+delivers anything. With nothing saved in Admin and no `config.learning.containerId`, the server
+assigns the project's `openbot` container as the default by itself once it exists. The runtime key
+cannot create it, so create it once, with `bun scripts/setup-learning.ts` from a computer that can
+sign in to Intelligence, or in Intelligence itself. `config.learning.autoAssign: false` turns the
+automatic assignment off. `config.learning.containerId` sets the initial default container
 (`CPK_INTELLIGENCE_LEARNING_CONTAINER_ID`) and `config.learning.revision` the skills revision
 (`CPK_INTELLIGENCE_SKILLS_REVISION`). Both are only starting values: settings saved in Admin →
 Automatic Learning take precedence, including switching it off. See

charts/openbot/templates/_helpers.tpl

@@ -336,6 +336,11 @@ and in whatever holds the release, which is not where `KEY_ENCRYPTION_KEY` belon
 - name: CPK_INTELLIGENCE_SKILLS_REVISION
   value: {{ . | quote }}
 {{- end }}
+{{- /* Absent, as it is under `--reuse-values`, means on: only an explicit false is written. */}}
+{{- if eq (toString $learning.autoAssign) "false" }}
+- name: OPENBOT_LEARNING_AUTO_ASSIGN
+  value: "false"
+{{- end }}
 - name: INTELLIGENCE_API_URL
   value: {{ .Values.config.intelligence.apiUrl | quote }}
 - name: INTELLIGENCE_GATEWAY_WS_URL

charts/openbot/values.yaml

@@ -161,13 +161,15 @@ config:
     gatewayWsUrl: ""
     # The two secret halves live under `secrets` below, never here.
   # Learning defaults on; collection and delivery require an existing, assigned container.
-  # Fresh self-hosted setup: run scripts/setup-learning.ts on a computer with Chrome/Edge access
-  # to Intelligence, then transfer its runtime key through your secret manager and use openbot here.
-  # Existing key-only installs create it through authenticated Intelligence administration first.
+  # With nothing saved in Admin and no containerId below, the server assigns the project's openbot
+  # container on its own once it exists; the runtime key cannot create it. Create it once with
+  # scripts/setup-learning.ts (or in Intelligence), from a computer that can sign in to Intelligence.
   # Optional initial defaults; saved Admin → Automatic Learning settings take precedence, including off.
   learning:
     containerId: ""
     revision: ""
+    # false stops the automatic assignment (OPENBOT_LEARNING_AUTO_ASSIGN=false).
+    autoAssign: true
   # How far one Bot may hand work to another.
   #
   # A Bot addressing another is a grant an administrator makes, and these are the ceilings on what