@copilotkit/runtime 1.55.3-canary.1776260990 → 1.56.0

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,