@copilotkit/runtime 1.55.3 → 1.56.1

package/src/v2/runtime/__tests__/debug-sse-response.test.ts

@@ -0,0 +1,302 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { Observable, of } from "rxjs";
+import { BaseEvent, EventType } from "@ag-ui/client";
+import type { ResolvedDebugConfig } from "@copilotkit/shared";
+
+const mockDebug = vi.fn();
+
+vi.mock("pino", () => ({
+  default: vi.fn(() => ({
+    child: vi.fn(() => ({ debug: mockDebug })),
+    debug: mockDebug,
+  })),
+}));
+
+vi.mock("pino-pretty", () => ({ default: vi.fn() }));
+
+vi.mock("../../telemetry", () => ({
+  telemetry: { capture: vi.fn() },
+}));
+
+import pino from "pino";
+import { createSseEventResponse } from "../handlers/shared/sse-response";
+
+function createTestObservable(events: BaseEvent[]): Observable<BaseEvent> {
+  return of(...events);
+}
+
+function createMockRequest(): Request {
+  return new Request("https://example.com/agent/test/run", {
+    method: "POST",
+  });
+}
+
+async function drainResponse(response: Response): Promise<void> {
+  const reader = response.body!.getReader();
+  while (true) {
+    const { done } = await reader.read();
+    if (done) break;
+  }
+}
+
+describe("createSseEventResponse debug logging", () => {
+  beforeEach(() => {
+    mockDebug.mockClear();
+  });
+
+  it("does not log when debug is undefined", async () => {
+    const response = createSseEventResponse({
+      request: createMockRequest(),
+      observableFactory: () => createTestObservable([]),
+    });
+
+    await drainResponse(response);
+
+    expect(mockDebug).not.toHaveBeenCalled();
+  });
+
+  it("logs lifecycle message on stream open", async () => {
+    const debug: ResolvedDebugConfig = {
+      enabled: true,
+      events: false,
+      lifecycle: true,
+      verbose: false,
+    };
+
+    const event: BaseEvent = {
+      type: EventType.RUN_STARTED,
+      threadId: "t-1",
+      runId: "r-1",
+    } as BaseEvent;
+
+    const response = createSseEventResponse({
+      request: createMockRequest(),
+      observableFactory: () => createTestObservable([event]),
+      debug,
+    });
+
+    await drainResponse(response);
+
+    expect(mockDebug).toHaveBeenCalledWith("SSE stream opened");
+  });
+
+  it("logs lifecycle completion with total eventCount even when event logging is off", async () => {
+    const debug: ResolvedDebugConfig = {
+      enabled: true,
+      events: false,
+      lifecycle: true,
+      verbose: false,
+    };
+
+    const events: BaseEvent[] = [
+      {
+        type: EventType.RUN_STARTED,
+        threadId: "t-1",
+        runId: "r-1",
+      } as BaseEvent,
+      {
+        type: EventType.RUN_FINISHED,
+        threadId: "t-1",
+        runId: "r-1",
+      } as BaseEvent,
+    ];
+
+    const response = createSseEventResponse({
+      request: createMockRequest(),
+      observableFactory: () => createTestObservable(events),
+      debug,
+    });
+
+    await drainResponse(response);
+
+    expect(mockDebug).toHaveBeenCalledWith(
+      { eventCount: 2, loggedEventCount: 0 },
+      "SSE stream completed",
+    );
+  });
+
+  it("logs lifecycle completion with matching eventCount and loggedEventCount when events enabled", async () => {
+    const debug: ResolvedDebugConfig = {
+      enabled: true,
+      events: true,
+      lifecycle: true,
+      verbose: false,
+    };
+
+    const events: BaseEvent[] = [
+      {
+        type: EventType.RUN_STARTED,
+        threadId: "t-1",
+        runId: "r-1",
+      } as BaseEvent,
+      {
+        type: EventType.RUN_FINISHED,
+        threadId: "t-1",
+        runId: "r-1",
+      } as BaseEvent,
+    ];
+
+    const response = createSseEventResponse({
+      request: createMockRequest(),
+      observableFactory: () => createTestObservable(events),
+      debug,
+    });
+
+    await drainResponse(response);
+
+    expect(mockDebug).toHaveBeenCalledWith(
+      { eventCount: 2, loggedEventCount: 2 },
+      "SSE stream completed",
+    );
+  });
+
+  it("logs events in summary mode when verbose is false", async () => {
+    const debug: ResolvedDebugConfig = {
+      enabled: true,
+      events: true,
+      lifecycle: false,
+      verbose: false,
+    };
+
+    const event: BaseEvent = {
+      type: EventType.TEXT_MESSAGE_START,
+      messageId: "msg-1",
+      role: "assistant",
+    } as BaseEvent;
+
+    const response = createSseEventResponse({
+      request: createMockRequest(),
+      observableFactory: () => createTestObservable([event]),
+      debug,
+    });
+
+    await drainResponse(response);
+
+    const eventEmittedCalls = mockDebug.mock.calls.filter(
+      (call) => call[call.length - 1] === "Event emitted",
+    );
+    expect(eventEmittedCalls.length).toBeGreaterThanOrEqual(1);
+
+    const [summaryArg] = eventEmittedCalls[0];
+    expect(summaryArg).toHaveProperty("type", EventType.TEXT_MESSAGE_START);
+    expect(summaryArg).toHaveProperty("messageId", "msg-1");
+    // In summary mode the full event object is not passed directly
+    expect(summaryArg).not.toHaveProperty("event");
+  });
+
+  it("logs events in verbose mode with full event object", async () => {
+    const debug: ResolvedDebugConfig = {
+      enabled: true,
+      events: true,
+      lifecycle: false,
+      verbose: true,
+    };
+
+    const event: BaseEvent = {
+      type: EventType.TEXT_MESSAGE_START,
+      messageId: "msg-1",
+      role: "assistant",
+    } as BaseEvent;
+
+    const response = createSseEventResponse({
+      request: createMockRequest(),
+      observableFactory: () => createTestObservable([event]),
+      debug,
+    });
+
+    await drainResponse(response);
+
+    const eventEmittedCalls = mockDebug.mock.calls.filter(
+      (call) => call[call.length - 1] === "Event emitted",
+    );
+    expect(eventEmittedCalls.length).toBeGreaterThanOrEqual(1);
+
+    const [verboseArg] = eventEmittedCalls[0];
+    expect(verboseArg).toHaveProperty("event");
+    expect(verboseArg.event).toEqual(event);
+  });
+
+  it("uses a pre-created logger instead of calling createLogger when one is provided", async () => {
+    const debug: ResolvedDebugConfig = {
+      enabled: true,
+      events: false,
+      lifecycle: true,
+      verbose: false,
+    };
+
+    const externalDebug = vi.fn();
+    const externalLogger = { debug: externalDebug } as any;
+
+    // Clear the pino mock call count so we can assert it was NOT called again
+    const pinoMock = pino as unknown as ReturnType<typeof vi.fn>;
+    pinoMock.mockClear();
+
+    const event: BaseEvent = {
+      type: EventType.RUN_STARTED,
+      threadId: "t-1",
+      runId: "r-1",
+    } as BaseEvent;
+
+    const response = createSseEventResponse({
+      request: createMockRequest(),
+      observableFactory: () => createTestObservable([event]),
+      debug,
+      logger: externalLogger,
+    });
+
+    await drainResponse(response);
+
+    // The external logger should have been used for lifecycle messages
+    expect(externalDebug).toHaveBeenCalledWith("SSE stream opened");
+    expect(externalDebug).toHaveBeenCalledWith(
+      { eventCount: 1, loggedEventCount: 0 },
+      "SSE stream completed",
+    );
+
+    // pino should NOT have been called – the pre-created logger was reused
+    expect(pinoMock).not.toHaveBeenCalled();
+  });
+
+  it("does not log events when events is disabled", async () => {
+    const debug: ResolvedDebugConfig = {
+      enabled: true,
+      events: false,
+      lifecycle: true,
+      verbose: false,
+    };
+
+    const events: BaseEvent[] = [
+      {
+        type: EventType.TEXT_MESSAGE_START,
+        messageId: "msg-1",
+        role: "assistant",
+      } as BaseEvent,
+      {
+        type: EventType.RUN_FINISHED,
+        threadId: "t-1",
+        runId: "r-1",
+      } as BaseEvent,
+    ];
+
+    const response = createSseEventResponse({
+      request: createMockRequest(),
+      observableFactory: () => createTestObservable(events),
+      debug,
+    });
+
+    await drainResponse(response);
+
+    const eventEmittedCalls = mockDebug.mock.calls.filter(
+      (call) => call[call.length - 1] === "Event emitted",
+    );
+    expect(eventEmittedCalls).toHaveLength(0);
+
+    // Only lifecycle calls should be present
+    const lifecycleCalls = mockDebug.mock.calls.filter(
+      (call) =>
+        call[call.length - 1] === "SSE stream opened" ||
+        call[call.length - 1] === "SSE stream completed",
+    );
+    expect(lifecycleCalls.length).toBeGreaterThanOrEqual(1);
+  });
+});

package/src/v2/runtime/__tests__/get-runtime-info.test.ts

@@ -1,7 +1,7 @@
 import { handleGetRuntimeInfo } from "../handlers/get-runtime-info";
 import { CopilotRuntime } from "../core/runtime";
 import { TranscriptionService } from "../transcription-service/transcription-service";
-import { describe, it, expect } from "vitest";
+import { describe, it, expect, vi } from "vitest";
 import type { AbstractAgent } from "@ag-ui/client";
 
 // Mock transcription service
@@ -117,6 +117,139 @@ describe("handleGetRuntimeInfo", () => {
     expect(data.a2uiEnabled).toBe(true);
   });
 
+  it("should include capabilities when agent implements getCapabilities", async () => {
+    const mockCapabilities = {
+      tools: { supported: true, clientProvided: true },
+      transport: { streaming: true },
+    };
+
+    const mockAgent = {
+      description: "Capable agent",
+      constructor: { name: "CapableAgent" },
+      getCapabilities: async () => mockCapabilities,
+    };
+
+    const runtime = new CopilotRuntime({
+      agents: {
+        capableAgent: mockAgent as unknown as AbstractAgent,
+      },
+    });
+
+    const response = await handleGetRuntimeInfo({
+      runtime,
+      request: mockRequest,
+    });
+
+    expect(response.status).toBe(200);
+
+    const data = await response.json();
+    expect(data.agents.capableAgent.capabilities).toEqual(mockCapabilities);
+  });
+
+  it("should omit capabilities when agent does not implement getCapabilities", async () => {
+    const mockAgent = {
+      description: "Basic agent",
+      constructor: { name: "BasicAgent" },
+    };
+
+    const runtime = new CopilotRuntime({
+      agents: {
+        basicAgent: mockAgent as unknown as AbstractAgent,
+      },
+    });
+
+    const response = await handleGetRuntimeInfo({
+      runtime,
+      request: mockRequest,
+    });
+
+    expect(response.status).toBe(200);
+
+    const data = await response.json();
+    expect(data.agents.basicAgent.capabilities).toBeUndefined();
+  });
+
+  it("should include empty capabilities object when getCapabilities returns {}", async () => {
+    const mockAgent = {
+      description: "Empty caps agent",
+      constructor: { name: "EmptyCapsAgent" },
+      getCapabilities: async () => ({}),
+    };
+
+    const runtime = new CopilotRuntime({
+      agents: {
+        emptyAgent: mockAgent as unknown as AbstractAgent,
+      },
+    });
+
+    const response = await handleGetRuntimeInfo({
+      runtime,
+      request: mockRequest,
+    });
+
+    expect(response.status).toBe(200);
+
+    const data = await response.json();
+    // {} is truthy, so it should be included in the response
+    expect(data.agents.emptyAgent.capabilities).toEqual({});
+  });
+
+  it("should isolate per-agent getCapabilities failures and log a warning", async () => {
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+    const failingAgent = {
+      description: "Failing agent",
+      constructor: { name: "FailingAgent" },
+      getCapabilities: async () => {
+        throw new Error("capability fetch failed");
+      },
+    };
+
+    const healthyAgent = {
+      description: "Healthy agent",
+      constructor: { name: "HealthyAgent" },
+      getCapabilities: async () => ({
+        tools: { supported: true },
+      }),
+    };
+
+    const runtime = new CopilotRuntime({
+      agents: {
+        failing: failingAgent as unknown as AbstractAgent,
+        healthy: healthyAgent as unknown as AbstractAgent,
+      },
+    });
+
+    const response = await handleGetRuntimeInfo({
+      runtime,
+      request: mockRequest,
+    });
+
+    expect(response.status).toBe(200);
+
+    const data = await response.json();
+    // Failing agent should still appear but without capabilities
+    expect(data.agents.failing).toEqual({
+      name: "failing",
+      description: "Failing agent",
+      className: "FailingAgent",
+    });
+    expect(data.agents.failing.capabilities).toBeUndefined();
+
+    // Healthy agent should have its capabilities
+    expect(data.agents.healthy.capabilities).toEqual({
+      tools: { supported: true },
+    });
+
+    // Error should be logged, not silently swallowed
+    expect(warnSpy).toHaveBeenCalledWith(
+      'Failed to fetch capabilities for agent "failing":',
+      "capability fetch failed",
+    );
+
+    warnSpy.mockRestore();
+  });
+
   it("should return 500 error when runtime.agents throws an error", async () => {
     const runtime = {
       get agents(): Record<string, AbstractAgent> {

package/src/v2/runtime/__tests__/middleware-sse-parser.test.ts

@@ -83,6 +83,56 @@ describe("parseSSEResponse", () => {
     });
   });
 
+  it("normalizes array content in TOOL_CALL_RESULT (MCP adapters)", async () => {
+    const response = buildSSEResponse([
+      { type: "RUN_STARTED", threadId: "t-1", runId: "r-1" },
+      {
+        type: "TOOL_CALL_RESULT",
+        toolCallId: "tc-1",
+        messageId: "m-result",
+        role: "tool",
+        content: [
+          { type: "text", text: '{"metric":"cpu","value":42}' },
+          { type: "text", text: " extra info" },
+        ],
+      },
+      { type: "RUN_FINISHED", threadId: "t-1", runId: "r-1" },
+    ]);
+    const result = await parseSSEResponse(response);
+    expect(result.messages).toContainEqual({
+      id: "m-result",
+      role: "tool",
+      content: '{"metric":"cpu","value":42} extra info',
+      toolCallId: "tc-1",
+    });
+  });
+
+  it("filters non-text parts when normalizing array content in TOOL_CALL_RESULT", async () => {
+    const response = buildSSEResponse([
+      { type: "RUN_STARTED", threadId: "t-1", runId: "r-1" },
+      {
+        type: "TOOL_CALL_RESULT",
+        toolCallId: "tc-1",
+        messageId: "m-result",
+        role: "tool",
+        content: [
+          { type: "text", text: "valid" },
+          { type: "image", data: "binary" },
+          null,
+          { type: "text", text: " part" },
+        ],
+      },
+      { type: "RUN_FINISHED", threadId: "t-1", runId: "r-1" },
+    ]);
+    const result = await parseSSEResponse(response);
+    expect(result.messages).toContainEqual({
+      id: "m-result",
+      role: "tool",
+      content: "valid part",
+      toolCallId: "tc-1",
+    });
+  });
+
   it("uses MESSAGES_SNAPSHOT when present", async () => {
     const snapshotMessages = [
       { id: "u-1", role: "user", content: "hi" },

package/src/v2/runtime/core/middleware-sse-parser.ts

@@ -167,14 +167,24 @@ export async function parseSSEResponse(
         break;
       }
 
-      case "TOOL_CALL_RESULT":
+      case "TOOL_CALL_RESULT": {
+        // langchain-mcp-adapters may send content as an array of
+        // {type:"text", text:string} objects instead of a plain string.
+        let resultContent = event.content;
+        if (Array.isArray(resultContent)) {
+          resultContent = resultContent
+            .filter((part: any) => part && typeof part.text === "string")
+            .map((part: any) => part.text)
+            .join("");
+        }
         messagesById.set(event.messageId, {
           id: event.messageId,
           role: "tool",
-          content: event.content,
+          content: resultContent,
           toolCallId: event.toolCallId,
         });
         break;
+      }
     }
   }
 

package/src/v2/runtime/core/runtime.ts

@@ -9,6 +9,11 @@ import {
   createLicenseChecker,
   type LicenseChecker,
 } from "@copilotkit/license-verifier";
+import {
+  type ResolvedDebugConfig,
+  resolveDebugConfig,
+  type DebugConfig,
+} from "@copilotkit/shared";
 import { AbstractAgent } from "@ag-ui/client";
 import type { MCPClientConfig } from "@ag-ui/mcp-apps-middleware";
 import { A2UIMiddlewareConfig } from "@ag-ui/a2ui-middleware";
@@ -17,6 +22,7 @@ import type {
   BeforeRequestMiddleware,
   AfterRequestMiddleware,
 } from "./middleware";
+import { createLogger, type CopilotRuntimeLogger } from "../../../lib/logger";
 import { TranscriptionService } from "../transcription-service/transcription-service";
 import { AgentRunner } from "../runner/agent-runner";
 import { InMemoryAgentRunner } from "../runner/in-memory";
@@ -56,9 +62,70 @@ interface CopilotRuntimeMiddlewares {
   openGenerativeUI?: OpenGenerativeUIConfig;
 }
 
+/**
+ * Context passed to agent factory functions for per-request agent resolution.
+ */
+export interface AgentFactoryContext {
+  /** The incoming HTTP request. */
+  request: Request;
+}
+
+/**
+ * A function that dynamically creates agents on a per-request basis.
+ * Useful for multi-tenant scenarios or request-scoped agent configuration.
+ */
+export type AgentsFactory = (
+  ctx: AgentFactoryContext,
+) => MaybePromise<NonEmptyRecord<Record<string, AbstractAgent>>>;
+
+/**
+ * Agents can be provided as:
+ * - A static record of agents
+ * - A Promise that resolves to a record of agents
+ * - A factory function that receives request context and returns agents (or a Promise of agents)
+ */
+export type AgentsConfig =
+  | MaybePromise<NonEmptyRecord<Record<string, AbstractAgent>>>
+  | AgentsFactory;
+
+/**
+ * Resolve an AgentsConfig value to a concrete record of agents.
+ * If the config is a factory function, it is called with the given request context.
+ * Otherwise it is awaited directly (static record or Promise).
+ */
+export async function resolveAgents(
+  agents: AgentsConfig,
+  request?: Request,
+): Promise<Record<string, AbstractAgent>> {
+  if (typeof agents === "function") {
+    if (!request) {
+      throw new Error(
+        "Agent factory function requires a request context, but none was provided.",
+      );
+    }
+    return agents({ request });
+  }
+  return agents;
+}
+
 interface BaseCopilotRuntimeOptions extends CopilotRuntimeMiddlewares {
-  /** Map of available agents (loaded lazily is fine). */
-  agents: MaybePromise<NonEmptyRecord<Record<string, AbstractAgent>>>;
+  /**
+   * Map of available agents, or a factory function for per-request agent resolution.
+   *
+   * Static record:
+   * ```ts
+   * agents: { support: new SupportAgent(), technical: new TechnicalAgent() }
+   * ```
+   *
+   * Factory function (called per-request):
+   * ```ts
+   * agents: ({ request }) => {
+   *   const tenantId = request.headers.get("x-tenant-id");
+   *   return { default: createAgentForTenant(tenantId) };
+   * }
+   * ```
+   */
+  agents: AgentsConfig;
   /** Optional transcription service for audio processing. */
   transcriptionService?: TranscriptionService;
   /** Optional *before* middleware – callback function or webhook URL. */
@@ -67,6 +134,8 @@ interface BaseCopilotRuntimeOptions extends CopilotRuntimeMiddlewares {
   afterRequestMiddleware?: AfterRequestMiddleware;
   /** Signed license token for server-side feature verification. Falls back to COPILOTKIT_LICENSE_TOKEN env var. */
   licenseToken?: string;
+  /** Enable debug logging for the event pipeline. */
+  debug?: DebugConfig;
 }
 
 export interface CopilotRuntimeUser {
@@ -120,6 +189,8 @@ export interface CopilotRuntimeLike {
   identifyUser?: IdentifyUserCallback;
   mode: RuntimeMode;
   licenseChecker?: LicenseChecker;
+  debug: ResolvedDebugConfig;
+  debugLogger?: CopilotRuntimeLogger;
 }
 
 export interface CopilotSseRuntimeLike extends CopilotRuntimeLike {
@@ -147,6 +218,8 @@ abstract class BaseCopilotRuntime implements CopilotRuntimeLike {
   public mcpApps: CopilotRuntimeOptions["mcpApps"];
   public openGenerativeUI: CopilotRuntimeOptions["openGenerativeUI"];
   public licenseChecker?: LicenseChecker;
+  public debug: ResolvedDebugConfig;
+  public debugLogger?: CopilotRuntimeLogger;
 
   abstract readonly intelligence?: CopilotKitIntelligence;
   abstract readonly mode: RuntimeMode;
@@ -170,6 +243,13 @@ abstract class BaseCopilotRuntime implements CopilotRuntimeLike {
     this.mcpApps = mcpApps;
     this.openGenerativeUI = openGenerativeUI;
     this.runner = runner;
+    this.debug = resolveDebugConfig(options.debug);
+    if (this.debug.enabled) {
+      this.debugLogger = createLogger({
+        level: "debug",
+        component: "copilotkit-debug",
+      });
+    }
   }
 }
 
@@ -326,4 +406,12 @@ export class CopilotRuntime implements CopilotRuntimeLike {
   get licenseChecker() {
     return this.delegate.licenseChecker;
   }
+
+  get debug(): ResolvedDebugConfig {
+    return this.delegate.debug;
+  }
+
+  get debugLogger(): CopilotRuntimeLogger | undefined {
+    return this.delegate.debugLogger;
+  }
 }