@copilotkit/runtime 1.55.3 → 1.56.0

package/src/v2/runtime/__tests__/agents-factory.test.ts

@@ -0,0 +1,136 @@
+import { describe, it, expect, vi } from "vitest";
+import { HttpAgent } from "@ag-ui/client";
+import {
+  resolveAgents,
+  type AgentsConfig,
+  type AgentFactoryContext,
+} from "../core/runtime";
+import { handleRunAgent } from "../handlers/handle-run";
+import { handleGetRuntimeInfo } from "../handlers/get-runtime-info";
+import { CopilotRuntime } from "../core/runtime";
+
+function createMockAgent(name = "test") {
+  return new HttpAgent({ url: `https://example.com/${name}` });
+}
+
+function createMockRuntime(agents: AgentsConfig) {
+  return {
+    agents,
+    transcriptionService: undefined,
+    beforeRequestMiddleware: undefined,
+    afterRequestMiddleware: undefined,
+    runner: { stop: vi.fn().mockResolvedValue(true) },
+    mode: "sse",
+  } as unknown as CopilotRuntime;
+}
+
+function createMockRequest(headers?: Record<string, string>) {
+  return new Request("https://example.com/agent/test/run", {
+    method: "POST",
+    headers: { "Content-Type": "application/json", ...headers },
+    body: JSON.stringify({ threadId: "thread-1", messages: [], state: {} }),
+  });
+}
+
+describe("resolveAgents", () => {
+  it("resolves a static record", async () => {
+    const agents = { default: createMockAgent() };
+    const result = await resolveAgents(agents);
+    expect(result).toBe(agents);
+  });
+
+  it("resolves a Promise", async () => {
+    const agents = { default: createMockAgent() };
+    const result = await resolveAgents(Promise.resolve(agents));
+    expect(result).toEqual(agents);
+  });
+
+  it("calls a factory function with request context", async () => {
+    const agent = createMockAgent();
+    const factory = vi.fn().mockReturnValue({ default: agent });
+    const request = createMockRequest({ "x-tenant-id": "tenant-123" });
+
+    const result = await resolveAgents(factory, request);
+
+    expect(factory).toHaveBeenCalledTimes(1);
+    expect(factory).toHaveBeenCalledWith({ request });
+    expect(result).toEqual({ default: agent });
+  });
+
+  it("calls an async factory function", async () => {
+    const agent = createMockAgent();
+    const factory = vi.fn().mockResolvedValue({ default: agent });
+    const request = createMockRequest();
+
+    const result = await resolveAgents(factory, request);
+    expect(factory).toHaveBeenCalledTimes(1);
+    expect(result).toEqual({ default: agent });
+  });
+
+  it("throws when factory is used without a request", async () => {
+    const factory = vi.fn().mockReturnValue({ default: createMockAgent() });
+
+    await expect(resolveAgents(factory)).rejects.toThrow(
+      "Agent factory function requires a request context",
+    );
+    expect(factory).not.toHaveBeenCalled();
+  });
+
+  it("factory can read request headers for per-tenant resolution", async () => {
+    const tenantAgentA = createMockAgent("tenant-a");
+    const tenantAgentB = createMockAgent("tenant-b");
+
+    const factory = ({ request }: AgentFactoryContext) => {
+      const tenantId = request.headers.get("x-tenant-id");
+      if (tenantId === "a") return { default: tenantAgentA };
+      return { default: tenantAgentB };
+    };
+
+    const requestA = createMockRequest({ "x-tenant-id": "a" });
+    const requestB = createMockRequest({ "x-tenant-id": "b" });
+
+    const resultA = await resolveAgents(factory, requestA);
+    expect(resultA.default).toBe(tenantAgentA);
+
+    const resultB = await resolveAgents(factory, requestB);
+    expect(resultB.default).toBe(tenantAgentB);
+  });
+});
+
+describe("handleRunAgent with agents factory", () => {
+  it("returns 404 when factory returns no matching agent", async () => {
+    const factory = vi.fn().mockReturnValue({
+      other: createMockAgent("other"),
+    });
+    const runtime = createMockRuntime(factory);
+    const request = createMockRequest();
+
+    const response = await handleRunAgent({
+      runtime,
+      request,
+      agentId: "nonexistent",
+    });
+
+    expect(response.status).toBe(404);
+    expect(factory).toHaveBeenCalledWith({ request });
+  });
+});
+
+describe("handleGetRuntimeInfo with agents factory", () => {
+  it("resolves factory and lists agents", async () => {
+    const factory = vi.fn().mockReturnValue({
+      support: createMockAgent("support"),
+      technical: createMockAgent("technical"),
+    });
+    const runtime = createMockRuntime(factory);
+    const request = createMockRequest();
+
+    const response = await handleGetRuntimeInfo({ runtime, request });
+
+    expect(response.status).toBe(200);
+    const body = await response.json();
+    expect(Object.keys(body.agents)).toContain("support");
+    expect(Object.keys(body.agents)).toContain("technical");
+    expect(factory).toHaveBeenCalledWith({ request });
+  });
+});

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> {