@copilotkit/runtime 1.56.5 → 1.57.0-canary.1778082736

package/src/v2/runtime/intelligence-platform/__tests__/intelligence-mcp-helper.test.ts

@@ -0,0 +1,239 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { BasicAgent } from "../../../../agent";
+import { LLMock, MCPMock } from "@copilotkit/aimock";
+import { streamText } from "ai";
+import {
+  mockStreamTextResponse,
+  textDelta,
+  finish,
+  collectEvents,
+} from "../../../../agent/__tests__/test-helpers";
+
+vi.mock("ai", () => ({
+  streamText: vi.fn(),
+  tool: vi.fn((config) => config),
+  stepCountIs: vi.fn((count: number) => ({ type: "stepCount", count })),
+}));
+
+vi.mock("@ai-sdk/openai", () => ({
+  createOpenAI: vi.fn(() => (modelId: string) => ({
+    modelId,
+    provider: "openai",
+  })),
+}));
+
+async function startMcpMock(): Promise<{ url: string; server: LLMock }> {
+  const mock = new MCPMock();
+  mock.addTool({
+    name: "bash",
+    description: "Run a bash command",
+    inputSchema: {
+      type: "object",
+      properties: { command: { type: "string" } },
+    },
+  });
+  mock.onToolCall("bash", () => "ok");
+  const server = new LLMock({ port: 0 });
+  server.mount("/mcp", mock);
+  await server.start();
+  return { url: server.url, server };
+}
+
+/**
+ * aimock redacts `Authorization` to `[REDACTED]` in its journal. Spy on
+ * `globalThis.fetch` to read unredacted headers off each outbound request to
+ * `mcpUrl`. The spy delegates to the real fetch so the round-trip completes.
+ */
+function spyOnFetch(mcpUrl: string): {
+  records: Array<Record<string, string>>;
+  restore: () => void;
+} {
+  const records: Array<Record<string, string>> = [];
+  const realFetch = globalThis.fetch;
+  const spy = vi
+    .spyOn(globalThis, "fetch")
+    .mockImplementation(async (input, init) => {
+      const url =
+        typeof input === "string"
+          ? input
+          : input instanceof URL
+            ? input.toString()
+            : input.url;
+      if (url.startsWith(mcpUrl)) {
+        const seen: Record<string, string> = {};
+        new Headers(init?.headers ?? {}).forEach((value, key) => {
+          seen[key.toLowerCase()] = value;
+        });
+        records.push(seen);
+      }
+      return realFetch(input, init);
+    });
+  return { records, restore: () => spy.mockRestore() };
+}
+
+const baseInput = {
+  threadId: "thread1",
+  runId: "run1",
+  messages: [],
+  tools: [],
+  context: [],
+  state: {},
+};
+
+describe("BuiltInAgent — Intelligence MCP auto-attach via forwardedProps", () => {
+  let llm: LLMock | undefined;
+  const originalEnv = process.env;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    process.env = { ...originalEnv };
+    process.env.OPENAI_API_KEY = "test-key";
+  });
+
+  afterEach(async () => {
+    process.env = originalEnv;
+    if (llm) {
+      await llm.stop().catch(() => {});
+      llm = undefined;
+    }
+  });
+
+  it("attaches the Intelligence MCP server when forwardedProps carries userId + apiKey + mcpUrl", async () => {
+    const { url, server } = await startMcpMock();
+    llm = server;
+
+    const recorder = spyOnFetch(`${url}/mcp`);
+    try {
+      const agent = new BasicAgent({ model: "openai/gpt-4o" });
+
+      vi.mocked(streamText).mockReturnValue(
+        mockStreamTextResponse([textDelta("hi"), finish()]) as any,
+      );
+
+      await collectEvents(
+        agent["run"]({
+          ...baseInput,
+          forwardedProps: {
+            copilotkitIntelligence: {
+              userId: "jordan-beamson",
+              apiKey: "cpk-proj_short_long",
+              mcpUrl: `${url}/mcp`,
+            },
+          },
+        }),
+      );
+
+      expect(recorder.records.length).toBeGreaterThan(0);
+      for (const headers of recorder.records) {
+        expect(headers["authorization"]).toBe("Bearer cpk-proj_short_long");
+        expect(headers["x-cpki-user-id"]).toBe("jordan-beamson");
+      }
+    } finally {
+      recorder.restore();
+    }
+  });
+
+  it("does NOT attach when forwardedProps is empty (no Intelligence wiring this run)", async () => {
+    const { url, server } = await startMcpMock();
+    llm = server;
+
+    const recorder = spyOnFetch(`${url}/mcp`);
+    try {
+      const agent = new BasicAgent({ model: "openai/gpt-4o" });
+
+      vi.mocked(streamText).mockReturnValue(
+        mockStreamTextResponse([finish()]) as any,
+      );
+      await collectEvents(agent["run"](baseInput));
+
+      expect(recorder.records.length).toBe(0);
+    } finally {
+      recorder.restore();
+    }
+  });
+
+  it("does NOT attach when only some of the three props are present", async () => {
+    const { url, server } = await startMcpMock();
+    llm = server;
+
+    const recorder = spyOnFetch(`${url}/mcp`);
+    try {
+      const agent = new BasicAgent({ model: "openai/gpt-4o" });
+
+      vi.mocked(streamText).mockReturnValue(
+        mockStreamTextResponse([finish()]) as any,
+      );
+      await collectEvents(
+        agent["run"]({
+          ...baseInput,
+          forwardedProps: {
+            copilotkitIntelligence: {
+              // userId + apiKey but no mcpUrl — should not attach.
+              userId: "jordan",
+              apiKey: "cpk-proj_xx",
+            },
+          },
+        }),
+      );
+
+      expect(recorder.records.length).toBe(0);
+    } finally {
+      recorder.restore();
+    }
+  });
+
+  it("does NOT attach when the user has already configured a server pointing at the same URL (explicit opt-in wins)", async () => {
+    const { url, server } = await startMcpMock();
+    llm = server;
+    const mcpUrl = `${url}/mcp`;
+
+    let userFetchCalls = 0;
+    const agent = new BasicAgent({
+      model: "openai/gpt-4o",
+      mcpServers: [
+        {
+          type: "http",
+          url: mcpUrl,
+          options: {
+            fetch: async (input, init) => {
+              userFetchCalls++;
+              const h = new Headers(init?.headers ?? {});
+              h.set("Authorization", "Bearer user-supplied");
+              h.set("X-Cpki-User-Id", "explicit-user");
+              return globalThis.fetch(input, { ...init, headers: h });
+            },
+          },
+        },
+      ],
+    });
+
+    const recorder = spyOnFetch(mcpUrl);
+    try {
+      vi.mocked(streamText).mockReturnValue(
+        mockStreamTextResponse([finish()]) as any,
+      );
+      await collectEvents(
+        agent["run"]({
+          ...baseInput,
+          forwardedProps: {
+            copilotkitIntelligence: {
+              userId: "from-runtime",
+              apiKey: "cpk-proj_runtime",
+              mcpUrl,
+            },
+          },
+        }),
+      );
+
+      expect(recorder.records.length).toBeGreaterThan(0);
+      // Only the user's fetch wrapper hit the wire — auto-attach skipped.
+      for (const headers of recorder.records) {
+        expect(headers["authorization"]).toBe("Bearer user-supplied");
+        expect(headers["x-cpki-user-id"]).toBe("explicit-user");
+      }
+      expect(userFetchCalls).toBeGreaterThan(0);
+    } finally {
+      recorder.restore();
+    }
+  });
+});

package/src/v2/runtime/intelligence-platform/client.ts

@@ -1,5 +1,17 @@
 import { logger } from "@copilotkit/shared";
 
+/**
+ * Header name carrying the per-call end-user identity that the CopilotKit
+ * Intelligence `/mcp` endpoint requires. Internal CopilotKit machinery — the
+ * runtime stamps this onto `agent.headers` after `identifyUser` resolves,
+ * and the auto-attach in `configureAgentForRequest` reads it back to gate
+ * MCP-server attachment and to populate the outbound `X-Cpki-User-Id`
+ * header on every MCP request. Not part of the public user API.
+ *
+ * @internal
+ */
+export const INTELLIGENCE_USER_ID_HEADER = "x-cpki-user-id";
+
 /**
  * Error thrown when an Intelligence platform HTTP request returns a non-2xx
  * status. Carries the HTTP {@link status} code so callers can branch on
@@ -64,6 +76,19 @@ export interface CopilotKitIntelligenceConfig {
   wsUrl: string;
   /** API key for authenticating with the intelligence platform */
   apiKey: string;
+  /**
+   * Enable the Intelligence platform's MCP server (bash + thread tools) on
+   * every `BuiltInAgent` run that resolves a user. The auto-attach is
+   * implemented in `configureAgentForRequest`: when this flag is `true`
+   * AND the runtime's `identifyUser` callback has placed a user-id onto
+   * the agent's forwarded headers AND the user has not already configured
+   * an MCP server pointing at the same URL, the server is appended to the
+   * agent's effective MCP server list for that run.
+   *
+   * Defaults to `false` — opt-in. Existing intelligence setups continue to
+   * work without the bash MCP server unless they flip this flag.
+   */
+  mcpServer?: boolean;
   /**
    * Initial listener invoked after a thread is created.
    * Prefer {@link CopilotKitIntelligence.onThreadCreated} for multiple listeners.
@@ -198,6 +223,40 @@ export interface ThreadMessagesResponse {
   messages: ThreadMessage[];
 }
 
+/**
+ * Persisted AG-UI event for the inspector's debugging views. The platform
+ * stores raw events keyed by run; the `_inspect` route returns them in
+ * replay order (oldest first) across every run that targeted the thread.
+ */
+export interface ThreadInspectEvent {
+  type: string;
+  [key: string]: unknown;
+}
+
+/**
+ * Response from {@link CopilotKitIntelligence.getThreadEvents}. Mirrors the
+ * `ThreadEventsResult` shape returned by the platform's
+ * `GET /api/_inspect/threads/:id/events` endpoint.
+ */
+export interface ThreadEventsResponse {
+  events: ThreadInspectEvent[];
+  /** Row IDs the platform failed to decode (raw column corrupted). */
+  decodeErrorRowIds: string[];
+  /** True when the platform hit its per-thread event cap. */
+  truncated: boolean;
+}
+
+/**
+ * Response from {@link CopilotKitIntelligence.getThreadState}. Mirrors the
+ * discriminated `ThreadStateResult` returned by the platform's
+ * `GET /api/_inspect/threads/:id/state` endpoint, which folds RFC 6902
+ * STATE_DELTA events on top of the latest STATE_SNAPSHOT.
+ */
+export type ThreadStateResponse =
+  | { kind: "no-snapshot" }
+  | { kind: "snapshot-decode-error" }
+  | { kind: "snapshot"; state: unknown; skippedDeltas: number };
+
 export interface AcquireThreadLockRequest {
   threadId: string;
   runId: string;
@@ -241,6 +300,7 @@ export class CopilotKitIntelligence {
   #runnerWsUrl: string;
   #clientWsUrl: string;
   #apiKey: string;
+  #mcpServerEnabled: boolean;
   #threadCreatedListeners = new Set<(thread: ThreadSummary) => void>();
   #threadUpdatedListeners = new Set<(thread: ThreadSummary) => void>();
   #threadDeletedListeners = new Set<(params: ThreadDeletedPayload) => void>();
@@ -252,6 +312,7 @@ export class CopilotKitIntelligence {
     this.#runnerWsUrl = deriveRunnerWsUrl(intelligenceWsUrl);
     this.#clientWsUrl = deriveClientWsUrl(intelligenceWsUrl);
     this.#apiKey = config.apiKey;
+    this.#mcpServerEnabled = config.mcpServer ?? false;
 
     if (config.onThreadCreated) {
       this.onThreadCreated(config.onThreadCreated);
@@ -340,6 +401,16 @@ export class CopilotKitIntelligence {
     return this.#apiKey;
   }
 
+  /** @internal Used by the runtime's auto-attach to populate `Authorization`. */
+  ɵgetApiKey(): string {
+    return this.#apiKey;
+  }
+
+  /** @internal Used by the runtime's auto-attach to gate MCP attachment. */
+  ɵisMcpServerEnabled(): boolean {
+    return this.#mcpServerEnabled;
+  }
+
   async #request<T>(method: string, path: string, body?: unknown): Promise<T> {
     const url = `${this.#apiUrl}${path}`;
 
@@ -556,6 +627,48 @@ export class CopilotKitIntelligence {
     );
   }
 
+  /**
+   * Fetch the persisted AG-UI event stream for a thread.
+   *
+   * Backed by the platform's `GET /api/_inspect/threads/:id/events`
+   * introspection endpoint (see Intelligence PR #144). Events are returned
+   * in replay order across every run that targeted the thread. The
+   * `_inspect/` prefix flags this as debug-only — production code paths
+   * must not depend on it.
+   *
+   * @throws {@link PlatformRequestError} on non-2xx responses.
+   */
+  async getThreadEvents(params: {
+    threadId: string;
+  }): Promise<ThreadEventsResponse> {
+    return this.#request<ThreadEventsResponse>(
+      "GET",
+      `/api/_inspect/threads/${encodeURIComponent(params.threadId)}/events`,
+    );
+  }
+
+  /**
+   * Fetch the current agent state for a thread.
+   *
+   * Backed by the platform's `GET /api/_inspect/threads/:id/state`
+   * introspection endpoint (see Intelligence PR #144). The platform folds
+   * RFC 6902 STATE_DELTA events on top of the latest STATE_SNAPSHOT, so
+   * the returned state reflects the thread's current state — not just the
+   * last snapshot. The discriminated response distinguishes "no snapshot
+   * persisted yet" from "snapshot present" so consumers can render the
+   * correct empty state.
+   *
+   * @throws {@link PlatformRequestError} on non-2xx responses.
+   */
+  async getThreadState(params: {
+    threadId: string;
+  }): Promise<ThreadStateResponse> {
+    return this.#request<ThreadStateResponse>(
+      "GET",
+      `/api/_inspect/threads/${encodeURIComponent(params.threadId)}/state`,
+    );
+  }
+
   /**
    * Mark a thread as archived.
    *