@copilotkit/runtime 1.55.3 → 1.56.1

package/src/v2/runtime/handlers/get-runtime-info.ts

@@ -1,4 +1,9 @@
-import { CopilotRuntimeLike, isIntelligenceRuntime } from "../core/runtime";
+import type { AgentCapabilities } from "@ag-ui/core";
+import {
+  CopilotRuntimeLike,
+  isIntelligenceRuntime,
+  resolveAgents,
+} from "../core/runtime";
 import {
   AgentDescription,
   RuntimeInfo,
@@ -26,22 +31,42 @@ interface HandleGetRuntimeInfoParameters {
 
 export async function handleGetRuntimeInfo({
   runtime,
+  request,
 }: HandleGetRuntimeInfoParameters) {
   try {
-    const agents = await runtime.agents;
+    const agents = await resolveAgents(runtime.agents, request);
+
+    const agentEntries = await Promise.all(
+      Object.entries(agents).map(async ([name, agent]) => {
+        let capabilities: AgentCapabilities | undefined;
+        try {
+          capabilities = agent.getCapabilities
+            ? await agent.getCapabilities()
+            : undefined;
+        } catch (error) {
+          // Per-agent isolation: a single agent failing to report capabilities
+          // must not take down the entire /info endpoint.
+          console.warn(
+            `Failed to fetch capabilities for agent "${name}":`,
+            error instanceof Error ? error.message : error,
+          );
+          capabilities = undefined;
+        }
 
-    const agentsDict = Object.entries(agents).reduce(
-      (acc, [name, agent]) => {
-        acc[name] = {
+        const description: AgentDescription = {
           name,
           description: agent.description,
           className: agent.constructor.name,
+          ...(capabilities ? { capabilities } : {}),
         };
-        return acc;
-      },
-      {} as Record<string, AgentDescription>,
+
+        return [name, description] as const;
+      }),
     );
 
+    const agentsDict: Record<string, AgentDescription> =
+      Object.fromEntries(agentEntries);
+
     const runtimeInfo: RuntimeInfo = {
       version: VERSION,
       agents: agentsDict,

package/src/v2/runtime/handlers/handle-connect.ts

@@ -29,7 +29,7 @@ export async function handleConnectAgent({
   });
 
   try {
-    const agent = await cloneAgentForRequest(runtime, agentId);
+    const agent = await cloneAgentForRequest(runtime, agentId, request);
     if (agent instanceof Response) {
       return agent;
     }

package/src/v2/runtime/handlers/handle-run.ts

@@ -30,7 +30,7 @@ export async function handleRunAgent({
   });
 
   try {
-    const agent = await cloneAgentForRequest(runtime, agentId);
+    const agent = await cloneAgentForRequest(runtime, agentId, request);
     if (agent instanceof Response) {
       return agent;
     }
@@ -55,6 +55,13 @@ export async function handleRunAgent({
     agent.setState(input.state);
     agent.threadId = input.threadId;
 
+    if (runtime.debug?.lifecycle && runtime.debugLogger) {
+      runtime.debugLogger.debug(
+        { agentName: agentId, threadId: input.threadId },
+        "Agent run started",
+      );
+    }
+
     if (isIntelligenceRuntime(runtime)) {
       return handleIntelligenceRun({
         runtime,
@@ -65,7 +72,14 @@ export async function handleRunAgent({
       });
     }
 
-    return handleSseRun({ runtime, request, agent, input });
+    return handleSseRun({
+      runtime,
+      request,
+      agent,
+      input,
+      debug: runtime.debug,
+      logger: runtime.debugLogger,
+    });
   } catch (error) {
     console.error("Error running agent:", error);
     console.error(

package/src/v2/runtime/handlers/handle-stop.ts

@@ -1,4 +1,5 @@
 import type { CopilotRuntimeLike } from "../core/runtime";
+import { resolveAgents } from "../core/runtime";
 import { EventType } from "@ag-ui/client";
 
 interface StopAgentParameters {
@@ -15,7 +16,7 @@ export async function handleStopAgent({
   threadId,
 }: StopAgentParameters) {
   try {
-    const agents = await runtime.agents;
+    const agents = await resolveAgents(runtime.agents, request);
 
     if (!agents[agentId]) {
       return new Response(

package/src/v2/runtime/handlers/intelligence/thread-names.ts

@@ -99,7 +99,7 @@ async function runTitleGenerationAttempt(params: {
   prompt: string;
 }): Promise<string | null> {
   const { runtime, request, agentId, threadId, prompt } = params;
-  const agent = await cloneAgentForRequest(runtime, agentId);
+  const agent = await cloneAgentForRequest(runtime, agentId, request);
   if (isHandlerResponse(agent)) {
     logger.warn(
       { agentId, threadId },

package/src/v2/runtime/handlers/shared/agent-utils.ts

@@ -5,7 +5,7 @@ import {
 } from "@ag-ui/client";
 import { A2UIMiddleware } from "@ag-ui/a2ui-middleware";
 import { MCPAppsMiddleware } from "@ag-ui/mcp-apps-middleware";
-import { CopilotRuntimeLike } from "../../core/runtime";
+import { CopilotRuntimeLike, resolveAgents } from "../../core/runtime";
 import { OpenGenerativeUIMiddleware } from "../../open-generative-ui-middleware";
 import { extractForwardableHeaders } from "../header-utils";
 import { logger } from "@copilotkit/shared";
@@ -28,8 +28,9 @@ export interface ConnectRequestBody extends RunAgentInput {
 export async function cloneAgentForRequest(
   runtime: CopilotRuntimeLike,
   agentId: string,
+  request?: Request,
 ): Promise<AbstractAgent | Response> {
-  const agents = await runtime.agents;
+  const agents = await resolveAgents(runtime.agents, request);
 
   if (!agents[agentId]) {
     return new Response(

package/src/v2/runtime/handlers/shared/sse-response.ts

@@ -1,6 +1,11 @@
 import { BaseEvent } from "@ag-ui/client";
 import { EventEncoder } from "@ag-ui/encoder";
 import { Observable, Subscription } from "rxjs";
+import { ResolvedDebugConfig } from "@copilotkit/shared";
+import {
+  createLogger,
+  type CopilotRuntimeLogger,
+} from "../../../../lib/logger";
 import { telemetry } from "../../telemetry";
 
 interface CreateSseEventResponseParams {
@@ -8,17 +13,27 @@ interface CreateSseEventResponseParams {
   observableFactory: () =>
     | Promise<Observable<BaseEvent>>
     | Observable<BaseEvent>;
+  debug?: ResolvedDebugConfig;
+  /** Pre-created logger instance to avoid creating a new pino logger per request. */
+  logger?: CopilotRuntimeLogger;
 }
 
 export function createSseEventResponse({
   request,
   observableFactory,
+  debug,
+  logger,
 }: CreateSseEventResponseParams): Response {
   const stream = new TransformStream();
   const writer = stream.writable.getWriter();
   const encoder = new EventEncoder();
   let streamClosed = false;
 
+  const debugLogger = debug?.enabled
+    ? (logger ??
+      createLogger({ level: "debug", component: "copilotkit-debug" }))
+    : undefined;
+
   const closeStream = async () => {
     if (!streamClosed) {
       try {
@@ -50,10 +65,29 @@ export function createSseEventResponse({
 
     telemetry.capture("oss.runtime.agent_execution_stream_started", {});
 
+    if (debug?.lifecycle) {
+      debugLogger!.debug("SSE stream opened");
+    }
+
+    let eventCount = 0;
+    let loggedEventCount = 0;
+
     subscription = observable.subscribe({
       next: async (event) => {
         if (!request.signal.aborted && !streamClosed) {
           try {
+            eventCount++;
+            if (debug?.events) {
+              loggedEventCount++;
+              if (debug.verbose) {
+                debugLogger!.debug({ event }, "Event emitted");
+              } else {
+                debugLogger!.debug(
+                  { type: event.type, ...summarizeEvent(event) },
+                  "Event emitted",
+                );
+              }
+            }
             await writer.write(encoder.encode(event));
           } catch (error) {
             if (error instanceof Error && error.name === "AbortError") {
@@ -66,11 +100,23 @@ export function createSseEventResponse({
         telemetry.capture("oss.runtime.agent_execution_stream_errored", {
           error: error instanceof Error ? error.message : String(error),
         });
+        if (debug?.lifecycle) {
+          debugLogger!.debug(
+            { error: error instanceof Error ? error.message : String(error) },
+            "SSE stream errored",
+          );
+        }
         logError(error);
         await closeStream();
       },
       complete: async () => {
         telemetry.capture("oss.runtime.agent_execution_stream_ended", {});
+        if (debug?.lifecycle) {
+          debugLogger!.debug(
+            { eventCount, loggedEventCount },
+            "SSE stream completed",
+          );
+        }
         await closeStream();
       },
     });
@@ -98,3 +144,26 @@ export function createSseEventResponse({
     },
   });
 }
+
+function summarizeEvent(event: BaseEvent): Record<string, unknown> {
+  const e = event as any;
+  const summary: Record<string, unknown> = {};
+
+  if (e.messageId) summary.messageId = e.messageId;
+  if (e.toolCallId) summary.toolCallId = e.toolCallId;
+  if (e.toolCallName) summary.toolCallName = e.toolCallName;
+  if (e.role) summary.role = e.role;
+  if (e.delta != null && typeof e.delta === "string")
+    summary.deltaLength = e.delta.length;
+  if (e.snapshot && typeof e.snapshot === "object")
+    summary.snapshotKeys = Object.keys(e.snapshot);
+  if (e.delta && Array.isArray(e.delta))
+    summary.operationCount = e.delta.length;
+  if (e.threadId) summary.threadId = e.threadId;
+  if (e.runId) summary.runId = e.runId;
+  if (e.message) summary.message = e.message;
+  if (e.code) summary.code = e.code;
+  if (e.stepName) summary.stepName = e.stepName;
+
+  return summary;
+}

package/src/v2/runtime/handlers/sse/run.ts

@@ -1,4 +1,6 @@
 import { AbstractAgent, RunAgentInput } from "@ag-ui/client";
+import { ResolvedDebugConfig } from "@copilotkit/shared";
+import { type CopilotRuntimeLogger } from "../../../../lib/logger";
 import { CopilotRuntimeLike } from "../../core/runtime";
 import { createSseEventResponse } from "../shared/sse-response";
 
@@ -7,6 +9,9 @@ interface HandleSseRunParams {
   request: Request;
   agent: AbstractAgent;
   input: RunAgentInput;
+  debug?: ResolvedDebugConfig;
+  /** Pre-created logger instance to avoid creating a new pino logger per request. */
+  logger?: CopilotRuntimeLogger;
 }
 
 export function handleSseRun({
@@ -14,9 +19,13 @@ export function handleSseRun({
   request,
   agent,
   input,
+  debug,
+  logger,
 }: HandleSseRunParams): Response {
   return createSseEventResponse({
     request,
+    debug,
+    logger,
     observableFactory: () =>
       runtime.runner.run({
         threadId: input.threadId,

package/tests/service-adapters/anthropic/anthropic-adapter.test.ts

@@ -374,4 +374,272 @@ describe("AnthropicAdapter", () => {
       });
     });
   });
+
+  describe("Unknown Tool Use Handling", () => {
+    it("should skip unknown tool_use blocks without crashing", async () => {
+      const systemMessage = new TextMessage("system", "System message");
+      const userMessage = new TextMessage("user", "Do something");
+
+      // Mock Anthropic to return a stream with an unknown tool_use block
+      mockAnthropicCreate.mockResolvedValue({
+        [Symbol.asyncIterator]: async function* () {
+          yield { type: "message_start", message: { id: "msg-1" } };
+          // Unknown tool_use block — tool name not in the actions list
+          yield {
+            type: "content_block_start",
+            content_block: {
+              type: "tool_use",
+              id: "tool-unknown",
+              name: "nonexistent_tool",
+            },
+          };
+          yield {
+            type: "content_block_delta",
+            delta: { type: "input_json_delta", partial_json: '{"query":' },
+          };
+          yield {
+            type: "content_block_delta",
+            delta: { type: "input_json_delta", partial_json: '"test"}' },
+          };
+          yield { type: "content_block_stop" };
+          // Then a normal text block
+          yield {
+            type: "content_block_start",
+            content_block: { type: "text" },
+          };
+          yield {
+            type: "content_block_delta",
+            delta: { type: "text_delta", text: "Here is the result." },
+          };
+          yield { type: "content_block_stop" };
+        },
+      });
+
+      const mockStream = {
+        sendTextMessageStart: vi.fn(),
+        sendTextMessageContent: vi.fn(),
+        sendTextMessageEnd: vi.fn(),
+        sendActionExecutionStart: vi.fn(),
+        sendActionExecutionArgs: vi.fn(),
+        sendActionExecutionEnd: vi.fn(),
+        complete: vi.fn(),
+      };
+
+      let streamCallbackDone: Promise<void>;
+      mockEventSource.stream.mockImplementation((callback: any) => {
+        streamCallbackDone = callback(mockStream);
+      });
+
+      await adapter.process({
+        threadId: "test-thread",
+        messages: [systemMessage, userMessage],
+        actions: [
+          {
+            name: "known_tool",
+            description: "A known tool",
+            parameters: [],
+            jsonSchema: '{"type":"object","properties":{}}',
+          },
+        ],
+        eventSource: mockEventSource,
+        forwardedParameters: {},
+      });
+
+      // Wait for async stream processing to complete
+      await streamCallbackDone!;
+
+      // Should NOT have sent action execution events for the unknown tool
+      expect(mockStream.sendActionExecutionStart).not.toHaveBeenCalled();
+      expect(mockStream.sendActionExecutionArgs).not.toHaveBeenCalled();
+      expect(mockStream.sendActionExecutionEnd).not.toHaveBeenCalled();
+
+      // Should still process the text block normally
+      expect(mockStream.sendTextMessageStart).toHaveBeenCalled();
+      expect(mockStream.sendTextMessageContent).toHaveBeenCalledWith({
+        messageId: "msg-1",
+        content: "Here is the result.",
+      });
+      expect(mockStream.sendTextMessageEnd).toHaveBeenCalled();
+      expect(mockStream.complete).toHaveBeenCalled();
+    });
+
+    it("should trigger fallback when only unknown tool_use blocks are returned", async () => {
+      const systemMessage = new TextMessage("system", "System message");
+      const userMessage = new TextMessage("user", "Do something");
+
+      const toolExecution = new ActionExecutionMessage({
+        id: "tool-prev",
+        name: "someAction",
+        arguments: "{}",
+      });
+
+      const toolResult = new ResultMessage({
+        actionExecutionId: "tool-prev",
+        result: "Previous result",
+      });
+
+      // Mock Anthropic to return ONLY an unknown tool_use block
+      mockAnthropicCreate.mockResolvedValue({
+        [Symbol.asyncIterator]: async function* () {
+          yield { type: "message_start", message: { id: "msg-1" } };
+          yield {
+            type: "content_block_start",
+            content_block: {
+              type: "tool_use",
+              id: "tool-unknown",
+              name: "nonexistent_tool",
+            },
+          };
+          yield {
+            type: "content_block_delta",
+            delta: { type: "input_json_delta", partial_json: "{}" },
+          };
+          yield { type: "content_block_stop" };
+        },
+      });
+
+      const mockStream = {
+        sendTextMessageStart: vi.fn(),
+        sendTextMessageContent: vi.fn(),
+        sendTextMessageEnd: vi.fn(),
+        sendActionExecutionStart: vi.fn(),
+        sendActionExecutionArgs: vi.fn(),
+        sendActionExecutionEnd: vi.fn(),
+        complete: vi.fn(),
+      };
+
+      let streamCallbackDone: Promise<void>;
+      mockEventSource.stream.mockImplementation((callback: any) => {
+        streamCallbackDone = callback(mockStream);
+      });
+
+      await adapter.process({
+        threadId: "test-thread",
+        messages: [systemMessage, userMessage, toolExecution, toolResult],
+        actions: [
+          {
+            name: "known_tool",
+            description: "A known tool",
+            parameters: [],
+            jsonSchema: '{"type":"object","properties":{}}',
+          },
+        ],
+        eventSource: mockEventSource,
+        forwardedParameters: {},
+      });
+
+      // Wait for async stream processing to complete
+      await streamCallbackDone!;
+
+      // Should NOT have sent action execution events
+      expect(mockStream.sendActionExecutionStart).not.toHaveBeenCalled();
+
+      // Should trigger fallback since hasReceivedContent should be false
+      expect(mockStream.sendTextMessageStart).toHaveBeenCalled();
+      expect(mockStream.sendTextMessageContent).toHaveBeenCalledWith({
+        messageId: expect.any(String),
+        content: "Previous result",
+      });
+      expect(mockStream.sendTextMessageEnd).toHaveBeenCalled();
+    });
+  });
+});
+
+describe("AnthropicAdapter max_tokens default", () => {
+  let mockAnthropicCreate: any;
+  let mockEventSource: any;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("should default max_tokens to 4096 when not specified", async () => {
+    const mockAnthropic = {
+      messages: {
+        create: vi.fn(),
+      },
+    };
+
+    const adapter = new AnthropicAdapter({ anthropic: mockAnthropic as any });
+    mockAnthropicCreate = mockAnthropic.messages.create;
+
+    mockAnthropicCreate.mockResolvedValue({
+      [Symbol.asyncIterator]: async function* () {},
+    });
+
+    mockEventSource = {
+      stream: vi.fn((callback) => {
+        const mockStream = {
+          sendTextMessageStart: vi.fn(),
+          sendTextMessageContent: vi.fn(),
+          sendTextMessageEnd: vi.fn(),
+          sendActionExecutionStart: vi.fn(),
+          sendActionExecutionArgs: vi.fn(),
+          sendActionExecutionEnd: vi.fn(),
+          complete: vi.fn(),
+        };
+        callback(mockStream);
+        return Promise.resolve();
+      }),
+    };
+
+    const systemMessage = new TextMessage("system", "System message");
+    const userMessage = new TextMessage("user", "Hello");
+
+    await adapter.process({
+      threadId: "test-thread",
+      messages: [systemMessage, userMessage],
+      actions: [],
+      eventSource: mockEventSource,
+      forwardedParameters: {},
+    });
+
+    const createCallArgs = mockAnthropicCreate.mock.calls[0][0];
+    expect(createCallArgs.max_tokens).toBe(4096);
+  });
+
+  it("should use provided maxTokens when specified", async () => {
+    const mockAnthropic = {
+      messages: {
+        create: vi.fn(),
+      },
+    };
+
+    const adapter = new AnthropicAdapter({ anthropic: mockAnthropic as any });
+    mockAnthropicCreate = mockAnthropic.messages.create;
+
+    mockAnthropicCreate.mockResolvedValue({
+      [Symbol.asyncIterator]: async function* () {},
+    });
+
+    mockEventSource = {
+      stream: vi.fn((callback) => {
+        const mockStream = {
+          sendTextMessageStart: vi.fn(),
+          sendTextMessageContent: vi.fn(),
+          sendTextMessageEnd: vi.fn(),
+          sendActionExecutionStart: vi.fn(),
+          sendActionExecutionArgs: vi.fn(),
+          sendActionExecutionEnd: vi.fn(),
+          complete: vi.fn(),
+        };
+        callback(mockStream);
+        return Promise.resolve();
+      }),
+    };
+
+    const systemMessage = new TextMessage("system", "System message");
+    const userMessage = new TextMessage("user", "Hello");
+
+    await adapter.process({
+      threadId: "test-thread",
+      messages: [systemMessage, userMessage],
+      actions: [],
+      eventSource: mockEventSource,
+      forwardedParameters: { maxTokens: 8192 },
+    });
+
+    const createCallArgs = mockAnthropicCreate.mock.calls[0][0];
+    expect(createCallArgs.max_tokens).toBe(8192);
+  });
 });