@copilotkit/runtime 1.55.3 → 1.56.0

package/src/agent/index.ts

@@ -20,6 +20,7 @@ import {
   StateSnapshotEvent,
   StateDeltaEvent,
 } from "@ag-ui/client";
+import type { AgentCapabilities } from "@ag-ui/core";
 import {
   streamText,
   LanguageModel,
@@ -817,6 +818,15 @@ export interface BuiltInAgentClassicConfig {
    * Example: `{ openai: { reasoningEffort: "high" } }`
    */
   providerOptions?: Record<string, any>;
+  /**
+   * Explicit agent capabilities. **Shallow-merged** at the category level on
+   * top of auto-inferred defaults — providing a category (e.g. `tools`)
+   * replaces that entire category, not individual fields within it.
+   *
+   * For example, `{ tools: { supported: true } }` will drop the inferred
+   * `clientProvided` value. Include all fields for any category you override.
+   */
+  capabilities?: Partial<AgentCapabilities>;
 }
 
 /**
@@ -854,6 +864,29 @@ export class BuiltInAgent extends AbstractAgent {
     return this.config?.overridableProperties?.includes(property) ?? false;
   }
 
+  async getCapabilities(): Promise<AgentCapabilities> {
+    const inferred: AgentCapabilities = {
+      tools: {
+        supported: true,
+        clientProvided: true,
+      },
+      transport: {
+        streaming: true,
+      },
+    };
+
+    if (!this.config.capabilities) {
+      return inferred;
+    }
+
+    // Shallow merge at the category level — explicit overrides replace
+    // entire categories when provided, inferred defaults fill the rest.
+    return {
+      ...inferred,
+      ...this.config.capabilities,
+    };
+  }
+
   run(input: RunAgentInput): Observable<BaseEvent> {
     if (isFactoryConfig(this.config)) {
       return this.runFactory(input, this.config);

package/src/lib/runtime/__tests__/v1-agent-factory.test.ts

@@ -0,0 +1,109 @@
+import { describe, it, expect, vi } from "vitest";
+import { HttpAgent } from "@ag-ui/client";
+import { CopilotRuntime } from "../copilot-runtime";
+import {
+  resolveAgents,
+  type AgentsConfig,
+} from "../../../v2/runtime/core/runtime";
+
+function createMockAgent(name = "test") {
+  return new HttpAgent({ url: `https://example.com/${name}` });
+}
+
+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("V1 CopilotRuntime with agent factory function", () => {
+  it("preserves factory function through constructor (does not spread to {})", () => {
+    const factory = vi.fn().mockReturnValue({
+      default: createMockAgent("default"),
+    });
+
+    const runtime = new CopilotRuntime({ agents: factory });
+
+    // The V2 instance should receive a function (factory), not an empty object.
+    // Before the fix, spreading a function produced {}, losing all agents.
+    const v2Agents = runtime.instance.agents;
+    expect(typeof v2Agents).toBe("function");
+  });
+
+  it("factory function resolves agents on each request", async () => {
+    const agentA = createMockAgent("tenant-a");
+    const agentB = createMockAgent("tenant-b");
+
+    const factory: AgentsConfig = ({ request }) => {
+      const tenantId = request.headers.get("x-tenant-id");
+      if (tenantId === "a") return { default: agentA };
+      return { default: agentB };
+    };
+
+    const runtime = new CopilotRuntime({ agents: factory });
+    const v2Agents = runtime.instance.agents;
+
+    const requestA = createMockRequest({ "x-tenant-id": "a" });
+    const resolvedA = await resolveAgents(v2Agents, requestA);
+    expect(resolvedA.default).toBe(agentA);
+
+    const requestB = createMockRequest({ "x-tenant-id": "b" });
+    const resolvedB = await resolveAgents(v2Agents, requestB);
+    expect(resolvedB.default).toBe(agentB);
+  });
+
+  it("merges endpoint agents with factory-resolved agents", async () => {
+    const factoryAgent = createMockAgent("factory-agent");
+    const factory = vi.fn().mockReturnValue({
+      dynamic: factoryAgent,
+    });
+
+    // Use remoteEndpoints to generate endpoint agents that should be merged
+    const runtime = new CopilotRuntime({
+      agents: factory,
+      remoteEndpoints: [
+        {
+          url: "https://example.com/endpoint",
+          onBeforeRequest: undefined,
+        },
+      ],
+    });
+
+    const v2Agents = runtime.instance.agents;
+    expect(typeof v2Agents).toBe("function");
+
+    const request = createMockRequest();
+    const resolved = await resolveAgents(v2Agents, request);
+
+    // Factory agent should be present
+    expect(resolved.dynamic).toBe(factoryAgent);
+    // Factory should have been called with request context
+    expect(factory).toHaveBeenCalledWith({ request });
+  });
+
+  it("static agents record still works after fix", async () => {
+    const agent = createMockAgent("static");
+
+    const runtime = new CopilotRuntime({
+      agents: { myAgent: agent },
+    });
+
+    const v2Agents = runtime.instance.agents;
+    const resolved = await resolveAgents(v2Agents);
+    expect(resolved.myAgent).toBe(agent);
+  });
+
+  it("promised agents record still works after fix", async () => {
+    const agent = createMockAgent("promised");
+
+    const runtime = new CopilotRuntime({
+      agents: Promise.resolve({ myAgent: agent }),
+    });
+
+    const v2Agents = runtime.instance.agents;
+    const resolved = await resolveAgents(v2Agents);
+    expect(resolved.myAgent).toBe(agent);
+  });
+});

package/src/lib/runtime/copilot-runtime.ts

@@ -23,6 +23,7 @@ import {
   getZodParameters,
   type PartialBy,
   isTelemetryDisabled,
+  type DebugConfig,
 } from "@copilotkit/shared";
 import type { RunAgentInput } from "@ag-ui/core";
 import { aguiToGQL } from "../../graphql/message-conversion/agui-to-gql";
@@ -35,8 +36,13 @@ import {
   type CopilotRuntimeOptions,
   type CopilotRuntimeOptions as CopilotRuntimeOptionsVNext,
   type AgentRunner,
+  type AgentsConfig,
+  type AgentsFactory,
+  type AgentFactoryContext,
   InMemoryAgentRunner,
 } from "../../v2/runtime";
+
+export type { AgentsConfig, AgentsFactory, AgentFactoryContext };
 import { TelemetryAgentRunner } from "./telemetry-agent-runner";
 import telemetry from "../telemetry-client";
 
@@ -287,6 +293,19 @@ export interface CopilotRuntimeConstructorParams_BASE<
 
   onStopGeneration?: OnStopGenerationHandler;
 
+  /**
+   * Enable debug logging for the runtime event pipeline.
+   * Pass `true` for full output, or an object for granular control:
+   *
+   * ```ts
+   * const runtime = new CopilotRuntime({
+   *   debug: true,
+   *   // or: debug: { events: true, lifecycle: true, verbose: false }
+   * });
+   * ```
+   */
+  debug?: DebugConfig;
+
   // /** Optional transcription service for audio processing. */
   // transcriptionService?: CopilotRuntimeOptionsVNext["transcriptionService"];
   // /** Optional *before* middleware – callback function or webhook URL. */
@@ -318,7 +337,7 @@ interface CopilotRuntimeConstructorParams<T extends Parameter[] | [] = []>
    *  – the `MaybePromise<NonEmptyRecord<T>>` constraint in `CopilotRuntimeOptionsVNext`
    *  – the `Record<string, AbstractAgent>` constraint in `both
    */
-  agents?: MaybePromise<NonEmptyRecord<Record<string, AbstractAgent>>>;
+  agents?: AgentsConfig;
 }
 
 /**
@@ -342,6 +361,22 @@ export class CopilotRuntime<const T extends Parameter[] | [] = []> {
       params?.remoteEndpoints ?? [],
     );
 
+    // Merge endpoint agents with user-provided agents.
+    // When agents is a factory function, wrap it so endpoint agents are merged
+    // at resolution time (spreading a function produces {} — silent data loss).
+    let mergedAgents: AgentsConfig;
+    if (typeof agents === "function") {
+      mergedAgents = async (ctx) => {
+        const resolved = await agents(ctx);
+        return { ...endpointAgents, ...resolved };
+      };
+    } else {
+      mergedAgents = Promise.resolve(agents).then((resolved) => ({
+        ...endpointAgents,
+        ...resolved,
+      }));
+    }
+
     // Determine the base runner (user-provided or default)
     const baseRunner = params?.runner ?? new InMemoryAgentRunner();
 
@@ -353,9 +388,10 @@ export class CopilotRuntime<const T extends Parameter[] | [] = []> {
       : new TelemetryAgentRunner({ runner: baseRunner });
 
     this.runtimeArgs = {
-      agents: { ...endpointAgents, ...agents },
+      agents: mergedAgents,
       runner,
       licenseToken: params?.licenseToken,
+      debug: params?.debug,
       // TODO: add support for transcriptionService from CopilotRuntimeOptionsVNext once it is ready
       // transcriptionService: params?.transcriptionService,
 

package/src/service-adapters/openai/__tests__/openai-v5-compat.test.ts

@@ -0,0 +1,177 @@
+import { describe, it, expect, vi } from "vitest";
+import {
+  isOpenAIV5,
+  getChatCompletionsForStreaming,
+  retrieveThreadRun,
+  submitToolOutputsStream,
+} from "../utils";
+import type OpenAI from "openai";
+
+/**
+ * Tests for OpenAI SDK v4/v5 compatibility layer.
+ *
+ * In v5, the `beta.chat` namespace was removed and promoted to `chat`.
+ * In v5, methods with multiple path params switched to named params
+ * (e.g. runs.retrieve(runId, { thread_id }) instead of runs.retrieve(threadId, runId)).
+ */
+
+function createMockV4Client() {
+  const streamFn = vi.fn();
+  return {
+    client: {
+      beta: {
+        chat: {
+          completions: { stream: streamFn },
+        },
+        threads: {
+          create: vi.fn(),
+          runs: {
+            retrieve: vi.fn().mockResolvedValue({ id: "run_xyz" }),
+            stream: vi.fn(),
+            submitToolOutputsStream: vi.fn(),
+          },
+          messages: {
+            create: vi.fn(),
+          },
+        },
+      },
+      chat: {
+        completions: {
+          stream: vi.fn(), // exists but should NOT be used for streaming in v4
+        },
+      },
+    } as unknown as OpenAI,
+    streamFn,
+  };
+}
+
+function createMockV5Client() {
+  const streamFn = vi.fn();
+  return {
+    client: {
+      // v5: beta.chat is gone, only beta.threads remains
+      beta: {
+        threads: {
+          create: vi.fn(),
+          runs: {
+            retrieve: vi.fn().mockResolvedValue({ id: "run_xyz" }),
+            stream: vi.fn(),
+            submitToolOutputsStream: vi.fn(),
+          },
+          messages: {
+            create: vi.fn(),
+          },
+        },
+      },
+      chat: {
+        completions: {
+          stream: streamFn,
+        },
+      },
+    } as unknown as OpenAI,
+    streamFn,
+  };
+}
+
+describe("isOpenAIV5", () => {
+  it("returns false for a v4 client (beta.chat exists)", () => {
+    const { client } = createMockV4Client();
+    expect(isOpenAIV5(client)).toBe(false);
+  });
+
+  it("returns true for a v5 client (beta.chat does not exist)", () => {
+    const { client } = createMockV5Client();
+    expect(isOpenAIV5(client)).toBe(true);
+  });
+
+  it("returns true when beta is entirely missing", () => {
+    const client = { chat: { completions: {} } } as unknown as OpenAI;
+    expect(isOpenAIV5(client)).toBe(true);
+  });
+});
+
+describe("getChatCompletionsForStreaming", () => {
+  it("returns beta.chat.completions for a v4 client", () => {
+    const { client } = createMockV4Client();
+    const completions = getChatCompletionsForStreaming(client);
+    // Should be the beta version, not the top-level one
+    expect(completions).not.toBe(client.chat.completions);
+  });
+
+  it("returns chat.completions for a v5 client", () => {
+    const { client } = createMockV5Client();
+    const completions = getChatCompletionsForStreaming(client);
+    expect(completions).toBe(client.chat.completions);
+  });
+
+  it("stream() on v4 calls beta.chat.completions.stream", () => {
+    const { client, streamFn } = createMockV4Client();
+    const completions = getChatCompletionsForStreaming(client);
+    completions.stream({ model: "gpt-4o", messages: [] });
+    expect(streamFn).toHaveBeenCalledWith({ model: "gpt-4o", messages: [] });
+  });
+
+  it("stream() on v5 calls chat.completions.stream", () => {
+    const { client, streamFn } = createMockV5Client();
+    const completions = getChatCompletionsForStreaming(client);
+    completions.stream({ model: "gpt-4o", messages: [] });
+    expect(streamFn).toHaveBeenCalledWith({ model: "gpt-4o", messages: [] });
+  });
+});
+
+describe("retrieveThreadRun", () => {
+  it("v4: calls retrieve with positional args (threadId, runId)", async () => {
+    const { client } = createMockV4Client();
+    const retrieveFn = client.beta.threads.runs.retrieve as ReturnType<
+      typeof vi.fn
+    >;
+
+    await retrieveThreadRun(client, "thread_abc", "run_xyz");
+
+    expect(retrieveFn).toHaveBeenCalledWith("thread_abc", "run_xyz");
+  });
+
+  it("v5: calls retrieve with named path params (runId, { thread_id })", async () => {
+    const { client } = createMockV5Client();
+    const retrieveFn = client.beta.threads.runs.retrieve as ReturnType<
+      typeof vi.fn
+    >;
+
+    await retrieveThreadRun(client, "thread_abc", "run_xyz");
+
+    expect(retrieveFn).toHaveBeenCalledWith("run_xyz", {
+      thread_id: "thread_abc",
+    });
+  });
+});
+
+describe("submitToolOutputsStream", () => {
+  it("v4: calls with positional args (threadId, runId, body)", () => {
+    const { client } = createMockV4Client();
+    const submitFn = client.beta.threads.runs
+      .submitToolOutputsStream as ReturnType<typeof vi.fn>;
+    const body = {
+      tool_outputs: [{ tool_call_id: "tc_1", output: "result" }],
+    };
+
+    submitToolOutputsStream(client, "thread_abc", "run_xyz", body);
+
+    expect(submitFn).toHaveBeenCalledWith("thread_abc", "run_xyz", body);
+  });
+
+  it("v5: calls with named path params (runId, { thread_id, ...body })", () => {
+    const { client } = createMockV5Client();
+    const submitFn = client.beta.threads.runs
+      .submitToolOutputsStream as ReturnType<typeof vi.fn>;
+    const body = {
+      tool_outputs: [{ tool_call_id: "tc_1", output: "result" }],
+    };
+
+    submitToolOutputsStream(client, "thread_abc", "run_xyz", body);
+
+    expect(submitFn).toHaveBeenCalledWith("run_xyz", {
+      thread_id: "thread_abc",
+      ...body,
+    });
+  });
+});

package/src/service-adapters/openai/openai-adapter.ts

@@ -61,6 +61,7 @@ import {
   convertActionInputToOpenAITool,
   convertMessageToOpenAIMessage,
   limitMessagesToTokenCount,
+  getChatCompletionsForStreaming,
 } from "./utils";
 import { randomUUID } from "@copilotkit/shared";
 import { convertServiceAdapterError, getSdkClientOptions } from "../shared";
@@ -203,7 +204,8 @@ export class OpenAIAdapter implements CopilotServiceAdapter {
 
     try {
       const openai = this.ensureOpenAI();
-      const stream = openai.beta.chat.completions.stream({
+      const completions = getChatCompletionsForStreaming(openai);
+      const stream = completions.stream({
         model: model,
         stream: true,
         messages: openaiMessages,

package/src/service-adapters/openai/openai-assistant-adapter.ts

@@ -43,6 +43,8 @@ import {
   convertActionInputToOpenAITool,
   convertMessageToOpenAIMessage,
   convertSystemMessageToAssistantAPI,
+  retrieveThreadRun,
+  submitToolOutputsStream,
 } from "./utils";
 import { RuntimeEventSource } from "../events";
 import { ActionInput } from "../../graphql/inputs/action.input";
@@ -186,7 +188,7 @@ export class OpenAIAssistantAdapter implements CopilotServiceAdapter {
     eventSource: RuntimeEventSource,
   ) {
     const openai = this.ensureOpenAI();
-    let run = await openai.beta.threads.runs.retrieve(threadId, runId);
+    let run = await retrieveThreadRun(openai, threadId, runId);
 
     if (!run.required_action) {
       throw new Error("No tool outputs required");
@@ -219,14 +221,10 @@ export class OpenAIAssistantAdapter implements CopilotServiceAdapter {
         };
       });
 
-    const stream = openai.beta.threads.runs.submitToolOutputsStream(
-      threadId,
-      runId,
-      {
-        tool_outputs: toolOutputs,
-        ...(this.disableParallelToolCalls && { parallel_tool_calls: false }),
-      },
-    );
+    const stream = submitToolOutputsStream(openai, threadId, runId, {
+      tool_outputs: toolOutputs,
+      ...(this.disableParallelToolCalls && { parallel_tool_calls: false }),
+    });
 
     await this.streamResponse(stream, eventSource);
     return runId;

package/src/service-adapters/openai/utils.ts

@@ -1,3 +1,4 @@
+import type OpenAI from "openai";
 import { Message } from "../../graphql/types/converted";
 import { ActionInput } from "../../graphql/inputs/action.input";
 import {
@@ -10,6 +11,105 @@ import {
 } from "openai/resources/chat";
 import { parseJson } from "@copilotkit/shared";
 
+/**
+ * OpenAI v4 exposes streaming completions under `beta.chat.completions`.
+ * v5 removed `beta.chat` and promoted streaming to `chat.completions`.
+ * These interfaces model the v4-specific shape so we can detect and access
+ * the beta namespace safely without `as any`.
+ */
+interface OpenAIV4BetaChat {
+  chat: {
+    completions: OpenAI["chat"]["completions"];
+  };
+}
+
+interface OpenAIV4Beta extends OpenAI.Beta {
+  chat: OpenAIV4BetaChat["chat"];
+}
+
+/**
+ * Type guard: checks whether the OpenAI client has the v4-era `beta.chat`
+ * namespace. Returns `false` for v5+ clients where `beta.chat` was removed.
+ */
+function hasV4BetaChat(beta: OpenAI["beta"] | undefined): beta is OpenAIV4Beta {
+  return beta != null && "chat" in beta && (beta as OpenAIV4Beta).chat != null;
+}
+
+/**
+ * Detects whether the provided OpenAI client is v5+ by checking for the
+ * removal of the `beta.chat` namespace (which was promoted to `chat` in v5).
+ */
+export function isOpenAIV5(openai: OpenAI): boolean {
+  return !hasV4BetaChat(openai.beta);
+}
+
+/**
+ * Returns the chat completions object that supports `.stream()`.
+ * In v4 this lives under `openai.beta.chat.completions`;
+ * in v5 it was promoted to `openai.chat.completions`.
+ */
+export function getChatCompletionsForStreaming(
+  openai: OpenAI,
+): OpenAI["chat"]["completions"] {
+  if (hasV4BetaChat(openai.beta)) {
+    return openai.beta.chat.completions;
+  }
+  return openai.chat.completions;
+}
+
+/**
+ * Retrieves a thread run, handling the v4→v5 API signature change.
+ * v4: retrieve(threadId, runId)
+ * v5: retrieve(runId, { thread_id: threadId })
+ */
+export async function retrieveThreadRun(
+  openai: OpenAI,
+  threadId: string,
+  runId: string,
+): Promise<OpenAI.Beta.Threads.Runs.Run> {
+  if (isOpenAIV5(openai)) {
+    // v5 switched to named path params. The type definitions from whichever
+    // SDK version is installed won't match both signatures, so we call through
+    // a generic function reference. This is the one unavoidable boundary
+    // between two incompatible SDK type surfaces.
+    const retrieve = openai.beta.threads.runs.retrieve as {
+      (...args: unknown[]): Promise<OpenAI.Beta.Threads.Runs.Run>;
+    };
+    return retrieve(runId, { thread_id: threadId });
+  }
+  return openai.beta.threads.runs.retrieve(threadId, runId);
+}
+
+/**
+ * Submits tool outputs as a stream, handling the v4→v5 API signature change.
+ * v4: submitToolOutputsStream(threadId, runId, body)
+ * v5: submitToolOutputsStream(runId, { thread_id, ...body })
+ */
+export function submitToolOutputsStream(
+  openai: OpenAI,
+  threadId: string,
+  runId: string,
+  body: {
+    tool_outputs: Array<{ tool_call_id: string; output: string }>;
+    parallel_tool_calls?: false;
+  },
+) {
+  if (isOpenAIV5(openai)) {
+    // Same boundary as retrieveThreadRun — v5 uses named path params.
+    const submit = openai.beta.threads.runs.submitToolOutputsStream as {
+      (
+        ...args: unknown[]
+      ): ReturnType<typeof openai.beta.threads.runs.submitToolOutputsStream>;
+    };
+    return submit(runId, { thread_id: threadId, ...body });
+  }
+  return openai.beta.threads.runs.submitToolOutputsStream(
+    threadId,
+    runId,
+    body,
+  );
+}
+
 export function limitMessagesToTokenCount(
   messages: any[],
   tools: any[],