@copilotkit/runtime 1.55.0-next.9 → 1.55.0

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

@@ -1,5 +1,8 @@
 export const errorResponse = (message: string, status: number) =>
-  Response.json({ error: message }, { status });
+  new Response(JSON.stringify({ error: message }), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
 
 export function isHandlerResponse(value: unknown): value is Response {
   return value instanceof Response;

package/src/v2/runtime/handlers/shared/resolve-intelligence-user.ts

@@ -1,7 +1,7 @@
 import {
   CopilotIntelligenceRuntimeLike,
   CopilotRuntimeUser,
-} from "../../runtime";
+} from "../../core/runtime";
 import { errorResponse } from "./json-response";
 import { isValidIdentifier } from "./intelligence-utils";
 

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

@@ -1,4 +1,4 @@
-import { CopilotRuntimeLike } from "../../runtime";
+import { CopilotRuntimeLike } from "../../core/runtime";
 import { createSseEventResponse } from "../shared/sse-response";
 import { extractForwardableHeaders } from "../header-utils";
 

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

@@ -1,5 +1,5 @@
 import { AbstractAgent, RunAgentInput } from "@ag-ui/client";
-import { CopilotRuntimeLike } from "../../runtime";
+import { CopilotRuntimeLike } from "../../core/runtime";
 import { createSseEventResponse } from "../shared/sse-response";
 
 interface HandleSseRunParams {

package/src/v2/runtime/hono.ts

@@ -0,0 +1,2 @@
+export * from "./endpoints/hono";
+export * from "./endpoints/hono-single";

package/src/v2/runtime/index.ts

@@ -1,4 +1,4 @@
-export * from "./runtime";
+export * from "./core/runtime";
 export * from "./endpoints";
 
 // Export agent runners and base types
@@ -18,3 +18,29 @@ export {
   type SubscribeToThreadsResponse,
   type UpdateThreadRequest,
 } from "./intelligence-platform";
+
+// Export framework-agnostic fetch handler
+export { createCopilotRuntimeHandler } from "./core/fetch-handler";
+export type {
+  CopilotRuntimeHandlerOptions,
+  CopilotRuntimeFetchHandler,
+} from "./core/fetch-handler";
+
+// Export hook types
+export type {
+  CopilotRuntimeHooks,
+  HookContext,
+  HandlerHookContext,
+  ResponseHookContext,
+  ErrorHookContext,
+  RouteInfo,
+} from "./core/hooks";
+
+// Export CORS config type
+export type { CopilotCorsConfig } from "./core/fetch-cors";
+
+// Deprecated type aliases for backward compatibility
+/** @deprecated Use `CopilotRuntimeFetchHandler` instead. Note: the new type takes `Request` directly, not `{ request: Request }`. */
+export type CopilotKitRequestHandler = (params: {
+  request: Request;
+}) => Promise<Response>;

package/src/v2/runtime/intelligence-platform/client.ts

@@ -157,6 +157,8 @@ export interface ThreadConnectionResponse {
   joinToken: string;
   /** Optional join code that can be shared with other clients to join the same channel. */
   joinCode?: string;
+  /** Lock metadata echoed back by the platform. */
+  lock?: ThreadLockInfo;
 }
 
 export interface SubscribeToThreadsRequest {
@@ -213,6 +215,28 @@ export interface AcquireThreadLockRequest {
   threadId: string;
   runId: string;
   userId: string;
+  /** Custom Redis key prefix for the lock (default: "thread"). */
+  lockKeyPrefix?: string;
+  /** Lock TTL in seconds. When set, the lock auto-expires after this duration. */
+  ttlSeconds?: number;
+}
+
+export interface RenewThreadLockRequest {
+  threadId: string;
+  runId: string;
+  /** New TTL to set on the lock in seconds. */
+  ttlSeconds: number;
+  /** Must match the prefix used when acquiring. */
+  lockKeyPrefix?: string;
+}
+
+export interface RenewThreadLockResponse {
+  ttlSeconds: number;
+}
+
+export interface ThreadLockInfo {
+  key: string;
+  ttlSeconds: number | null;
 }
 
 interface ThreadEnvelope {
@@ -596,7 +620,32 @@ export class CopilotKitIntelligence {
     return this.#request<ThreadConnectionResponse>(
       "POST",
       `/api/threads/${encodeURIComponent(params.threadId)}/lock`,
-      { runId: params.runId, userId: params.userId },
+      {
+        runId: params.runId,
+        userId: params.userId,
+        ...(params.lockKeyPrefix !== undefined
+          ? { lockKeyPrefix: params.lockKeyPrefix }
+          : {}),
+        ...(params.ttlSeconds !== undefined
+          ? { ttlSeconds: params.ttlSeconds }
+          : {}),
+      },
+    );
+  }
+
+  async ɵrenewThreadLock(
+    params: RenewThreadLockRequest,
+  ): Promise<RenewThreadLockResponse> {
+    return this.#request<RenewThreadLockResponse>(
+      "PATCH",
+      `/api/threads/${encodeURIComponent(params.threadId)}/lock`,
+      {
+        runId: params.runId,
+        ttlSeconds: params.ttlSeconds,
+        ...(params.lockKeyPrefix !== undefined
+          ? { lockKeyPrefix: params.lockKeyPrefix }
+          : {}),
+      },
     );
   }
 

package/src/v2/runtime/node.ts

@@ -0,0 +1,6 @@
+export { createCopilotNodeListener } from "./endpoints/node";
+export {
+  createCopilotNodeHandler,
+  createNodeFetchHandler,
+} from "./endpoints/node-fetch-handler";
+export type { NodeFetchHandler } from "./endpoints/node-fetch-handler";

package/src/v2/runtime/open-generative-ui-middleware.ts

@@ -0,0 +1,373 @@
+import {
+  Middleware,
+  RunAgentInput,
+  AbstractAgent,
+  BaseEvent,
+  EventType,
+  ToolCallStartEvent,
+  ToolCallArgsEvent,
+  ActivitySnapshotEvent,
+  ActivityDeltaEvent,
+} from "@ag-ui/client";
+import { Observable } from "rxjs";
+import * as clarinet from "clarinet";
+
+const TOOL_NAME = "generateSandboxedUi";
+const ACTIVITY_TYPE = "open-generative-ui";
+
+/**
+ * Parsed parameters from the generateSandboxedUi tool call.
+ */
+export interface GenerateSandboxedUIParams {
+  initialHeight?: number;
+  placeholderMessages?: string[];
+  css?: string;
+  html?: string;
+  jsFunctions?: string;
+  jsExpressions?: string[];
+}
+
+/**
+ * Callback invoked by ArgsParser whenever a parameter (or array item) finishes parsing.
+ */
+export type OnParamEvent = (event: BaseEvent) => void;
+
+/**
+ * Tracks incremental JSON parsing state for a single tool call's arguments.
+ * Emits activity events via the onEvent callback as parameters complete.
+ */
+export class ArgsParser {
+  private parser: ReturnType<typeof clarinet.parser>;
+  private currentKey: string | null = null;
+  private depth = 0;
+  private currentArrayKey: string | null = null;
+  private snapshotEmitted = false;
+
+  // Streaming html state — reads parser.textNode to emit incremental chunks
+  private streamingHtmlKey = false;
+  private htmlEmittedLength = 0;
+  private htmlArrayEmitted = false;
+
+  public readonly params: GenerateSandboxedUIParams = {};
+  public readonly messageId: string;
+  private readonly onEvent: OnParamEvent;
+
+  constructor(toolCallId: string, onEvent: OnParamEvent) {
+    this.messageId = `${toolCallId}-activity`;
+    this.onEvent = onEvent;
+    this.parser = clarinet.parser();
+
+    this.parser.onopenobject = (key: string | undefined) => {
+      this.depth++;
+      if (key !== undefined && this.depth === 1) {
+        this.currentKey = key;
+        this.initHtmlStreaming(key);
+      }
+    };
+
+    this.parser.onkey = (key: string) => {
+      if (this.depth === 1) {
+        this.currentKey = key;
+        this.initHtmlStreaming(key);
+      }
+    };
+
+    this.parser.onvalue = (value: string | boolean | number | null) => {
+      if (this.depth === 1 && this.currentKey) {
+        if (this.currentArrayKey) {
+          const strValue = String(value);
+          if (this.currentArrayKey === "jsExpressions") {
+            if (!this.params.jsExpressions) this.params.jsExpressions = [];
+            this.params.jsExpressions.push(strValue);
+          } else if (this.currentArrayKey === "placeholderMessages") {
+            if (!this.params.placeholderMessages)
+              this.params.placeholderMessages = [];
+            this.params.placeholderMessages.push(strValue);
+          }
+          this.emitArrayItemDelta(this.currentArrayKey, strValue);
+        } else if (this.streamingHtmlKey) {
+          // HTML string completed — flush any remaining content immediately + htmlComplete
+          const fullHtml = value != null ? String(value) : "";
+          this.params.html = fullHtml || undefined;
+          this.emitPendingHtml(fullHtml);
+          this.emitParamDelta("htmlComplete", true);
+          this.streamingHtmlKey = false;
+        } else {
+          this.setParam(this.currentKey, value);
+        }
+      }
+    };
+
+    this.parser.onopenarray = () => {
+      if (this.depth === 1 && this.currentKey) {
+        const key = this.currentKey;
+        if (key === "jsExpressions" || key === "placeholderMessages") {
+          this.currentArrayKey = key;
+          if (key === "jsExpressions") this.params.jsExpressions = [];
+          else this.params.placeholderMessages = [];
+          // Emit a delta to create the array in the activity content.
+          // Subsequent "add" ops with path "/<key>/-" append to this array.
+          this.emitParamDelta(key, []);
+        }
+      }
+    };
+
+    this.parser.onclosearray = () => {
+      if (this.depth === 1) {
+        if (this.currentArrayKey === "jsExpressions") {
+          this.emitParamDelta("jsExpressionsComplete", true);
+        }
+        this.currentArrayKey = null;
+      }
+    };
+
+    this.parser.oncloseobject = () => {
+      this.depth--;
+    };
+
+    this.parser.onerror = (err: Error) => {
+      console.warn(
+        "[OpenGenerativeUI] JSON parse error in streaming args, resuming:",
+        err?.message ?? err,
+      );
+      // Reset error state so parsing can continue with the next chunk
+      this.parser.error = null;
+      this.parser.resume();
+    };
+  }
+
+  write(chunk: string): void {
+    this.parser.write(chunk);
+    this.flushHtmlChunks();
+  }
+
+  private initHtmlStreaming(key: string): void {
+    if (key === "html") {
+      this.streamingHtmlKey = true;
+      this.htmlEmittedLength = 0;
+      this.htmlArrayEmitted = false;
+    }
+  }
+
+  /**
+   * Read clarinet's internal textNode buffer to emit html chunks incrementally.
+   * Called after every write() so partial string content is emitted as it streams in.
+   */
+  private flushHtmlChunks(): void {
+    if (!this.streamingHtmlKey) return;
+    const textNode = (this.parser as any).textNode;
+    if (typeof textNode !== "string") return;
+    if (textNode.length === this.htmlEmittedLength) return;
+
+    this.emitPendingHtml(textNode);
+  }
+
+  /**
+   * Emit accumulated html content since the last emission.
+   * Called by flushHtmlChunks and directly when html completes.
+   */
+  private emitPendingHtml(textNode: string): void {
+    const newContent = textNode.slice(this.htmlEmittedLength);
+    if (newContent.length === 0) return;
+
+    if (!this.htmlArrayEmitted) {
+      this.htmlArrayEmitted = true;
+      this.emitParamDelta("html", []);
+    }
+    this.emitArrayItemDelta("html", newContent);
+    this.htmlEmittedLength = textNode.length;
+  }
+
+  private setParam(key: string, value: string | boolean | number | null): void {
+    switch (key) {
+      case "initialHeight":
+        this.params.initialHeight =
+          typeof value === "number" ? value : undefined;
+        this.emitSnapshot();
+        break;
+      case "css":
+        this.params.css = value != null ? String(value) : undefined;
+        this.emitParamDelta("css", this.params.css);
+        this.emitParamDelta("cssComplete", true);
+        break;
+      case "jsFunctions":
+        this.params.jsFunctions = value != null ? String(value) : undefined;
+        this.emitParamDelta("jsFunctions", this.params.jsFunctions);
+        this.emitParamDelta("jsFunctionsComplete", true);
+        break;
+    }
+  }
+
+  private emitSnapshot(): void {
+    if (this.snapshotEmitted) return;
+    this.snapshotEmitted = true;
+
+    const event: ActivitySnapshotEvent = {
+      type: EventType.ACTIVITY_SNAPSHOT,
+      messageId: this.messageId,
+      activityType: ACTIVITY_TYPE,
+      content: { initialHeight: this.params.initialHeight, generating: true },
+    };
+    this.onEvent(event);
+  }
+
+  private emitParamDelta(key: string, value: unknown): void {
+    const event: ActivityDeltaEvent = {
+      type: EventType.ACTIVITY_DELTA,
+      messageId: this.messageId,
+      activityType: ACTIVITY_TYPE,
+      patch: [{ op: "add", path: `/${key}`, value }],
+    };
+    this.onEvent(event);
+  }
+
+  private emitArrayItemDelta(arrayKey: string, value: string): void {
+    const event: ActivityDeltaEvent = {
+      type: EventType.ACTIVITY_DELTA,
+      messageId: this.messageId,
+      activityType: ACTIVITY_TYPE,
+      patch: [{ op: "add", path: `/${arrayKey}/-`, value }],
+    };
+    this.onEvent(event);
+  }
+}
+
+/**
+ * Extract EventWithState type from Middleware.runNextWithState return type
+ */
+type ExtractObservableType<T> = T extends Observable<infer U> ? U : never;
+type RunNextWithStateReturn = ReturnType<Middleware["runNextWithState"]>;
+type EventWithState = ExtractObservableType<RunNextWithStateReturn>;
+
+export class OpenGenerativeUIMiddleware extends Middleware {
+  run(input: RunAgentInput, next: AbstractAgent): Observable<BaseEvent> {
+    return this.processStream(this.runNextWithState(input, next));
+  }
+
+  private processStream(
+    source: Observable<EventWithState>,
+  ): Observable<BaseEvent> {
+    return new Observable<BaseEvent>((subscriber) => {
+      let heldRunFinished: EventWithState | null = null;
+      // Track active generateSandboxedUi tool call IDs → their streaming parser
+      const activeParsers = new Map<string, ArgsParser>();
+      // Hold genui tool call events until the first activity event is emitted
+      const heldToolCallEvents = new Map<string, BaseEvent[]>();
+      const flushedToolCalls = new Set<string>();
+
+      const flushHeldEvents = (toolCallId: string) => {
+        if (flushedToolCalls.has(toolCallId)) return;
+        flushedToolCalls.add(toolCallId);
+        const held = heldToolCallEvents.get(toolCallId);
+        if (held) {
+          for (const e of held) {
+            subscriber.next(e);
+          }
+          heldToolCallEvents.delete(toolCallId);
+        }
+      };
+
+      const subscription = source.subscribe({
+        next: (eventWithState) => {
+          const event = eventWithState.event;
+
+          if (heldRunFinished) {
+            subscriber.next(heldRunFinished.event);
+            heldRunFinished = null;
+          }
+
+          if (event.type === EventType.RUN_FINISHED) {
+            heldRunFinished = eventWithState;
+            return;
+          }
+
+          // Hold TOOL_CALL_START for genui until the first activity event
+          if (event.type === EventType.TOOL_CALL_START) {
+            const startEvent = event as ToolCallStartEvent;
+            if (startEvent.toolCallName === TOOL_NAME) {
+              heldToolCallEvents.set(startEvent.toolCallId, [event]);
+              activeParsers.set(
+                startEvent.toolCallId,
+                new ArgsParser(startEvent.toolCallId, (activityEvent) => {
+                  subscriber.next(activityEvent);
+                  flushHeldEvents(startEvent.toolCallId);
+                }),
+              );
+              return;
+            }
+          }
+
+          // Hold or emit TOOL_CALL_ARGS for genui tool calls
+          if (event.type === EventType.TOOL_CALL_ARGS) {
+            const argsEvent = event as ToolCallArgsEvent;
+            const parser = activeParsers.get(argsEvent.toolCallId);
+            if (parser) {
+              if (!flushedToolCalls.has(argsEvent.toolCallId)) {
+                heldToolCallEvents.get(argsEvent.toolCallId)!.push(event);
+              } else {
+                subscriber.next(event);
+              }
+              parser.write(argsEvent.delta);
+              return;
+            }
+          }
+
+          // Hold or emit TOOL_CALL_END for genui tool calls
+          if (event.type === EventType.TOOL_CALL_END) {
+            const endEvent = event as { toolCallId: string } & BaseEvent;
+            const parser = activeParsers.get(endEvent.toolCallId);
+            if (parser) {
+              // Mark generation complete
+              const completeEvent: ActivityDeltaEvent = {
+                type: EventType.ACTIVITY_DELTA,
+                messageId: parser.messageId,
+                activityType: ACTIVITY_TYPE,
+                patch: [{ op: "add", path: "/generating", value: false }],
+              };
+              subscriber.next(completeEvent);
+
+              if (!flushedToolCalls.has(endEvent.toolCallId)) {
+                heldToolCallEvents.get(endEvent.toolCallId)!.push(event);
+              } else {
+                subscriber.next(event);
+              }
+              return;
+            }
+          }
+
+          subscriber.next(event);
+        },
+        error: (err) => {
+          // Flush any held tool call events so downstream sees them before the error
+          for (const [, events] of heldToolCallEvents) {
+            for (const event of events) {
+              subscriber.next(event);
+            }
+          }
+          heldToolCallEvents.clear();
+
+          if (heldRunFinished) {
+            subscriber.next(heldRunFinished.event);
+            heldRunFinished = null;
+          }
+          subscriber.error(err);
+        },
+        complete: () => {
+          // Flush any remaining held tool call events (e.g. parser never emitted)
+          heldToolCallEvents.forEach((_, toolCallId) => {
+            flushHeldEvents(toolCallId);
+          });
+
+          if (heldRunFinished) {
+            subscriber.next(heldRunFinished.event);
+            heldRunFinished = null;
+          }
+          activeParsers.clear();
+          subscriber.complete();
+        },
+      });
+
+      return () => subscription.unsubscribe();
+    });
+  }
+}

package/src/v2/runtime/runner/intelligence.ts

@@ -26,6 +26,10 @@ export interface IntelligenceAgentRunnerOptions {
   url: string;
   /** Optional Phoenix socket auth token used during websocket connect. */
   authToken?: string;
+  /** Max delay (ms) for WebSocket reconnect backoff. @default 10_000 */
+  maxReconnectMs?: number;
+  /** Max delay (ms) for channel rejoin backoff. @default 30_000 */
+  maxRejoinMs?: number;
 }
 
 interface ThreadState {
@@ -59,10 +63,10 @@ export class IntelligenceAgentRunner extends AgentRunner {
    *  - Each run gets its own independent retry budget.
    *
    * reconnectAfterMs — delay before Phoenix reconnects the WebSocket
-   *   after an unclean close. 100ms base, doubling up to a 10s cap.
+   *   after an unclean close. 100ms base, doubling up to maxReconnectMs (default 10s).
    *
    * rejoinAfterMs — delay before Phoenix re-joins a channel that
-   *   entered the "errored" state. 1s base, doubling up to 30s cap.
+   *   entered the "errored" state. 1s base, doubling up to maxRejoinMs (default 30s).
    *
    * These are set explicitly because Phoenix's default schedule is a
    * fixed stepped array (not exponential), and any code that calls
@@ -73,8 +77,14 @@ export class IntelligenceAgentRunner extends AgentRunner {
   private createSocket(): Socket {
     const socket = new Socket(this.options.url, {
       ...(this.options.authToken ? { authToken: this.options.authToken } : {}),
-      reconnectAfterMs: phoenixExponentialBackoff(100, 10_000),
-      rejoinAfterMs: phoenixExponentialBackoff(1_000, 30_000),
+      reconnectAfterMs: phoenixExponentialBackoff(
+        100,
+        this.options.maxReconnectMs ?? 10_000,
+      ),
+      rejoinAfterMs: phoenixExponentialBackoff(
+        1_000,
+        this.options.maxRejoinMs ?? 30_000,
+      ),
     });
     socket.connect();
     return socket;

package/src/v2/runtime/telemetry/telemetry-client.ts

@@ -1,4 +1,7 @@
+import { Analytics } from "@segment/analytics-node";
 import { AnalyticsEvents } from "./events";
+import { flattenObject } from "./utils";
+import { v4 as uuidv4 } from "uuid";
 import scarfClient from "./scarf-client";
 
 export function isTelemetryDisabled(): boolean {
@@ -14,8 +17,11 @@ export function isTelemetryDisabled(): boolean {
 }
 
 export class TelemetryClient {
+  segment: Analytics | undefined;
+  globalProperties: Record<string, any> = {};
   private telemetryDisabled: boolean = false;
   private sampleRate: number = 0.05;
+  private anonymousId = `anon_${uuidv4()}`;
 
   constructor({
     telemetryDisabled,
@@ -25,7 +31,21 @@ export class TelemetryClient {
     sampleRate?: number;
   } = {}) {
     this.telemetryDisabled = telemetryDisabled ?? isTelemetryDisabled();
+
+    if (this.telemetryDisabled) {
+      this.setSampleRate(sampleRate);
+      return;
+    }
+
     this.setSampleRate(sampleRate);
+
+    const writeKey =
+      process.env.COPILOTKIT_SEGMENT_WRITE_KEY ||
+      "n7XAZtQCGS2v1vvBy3LgBCv2h3Y8whja";
+
+    this.segment = new Analytics({
+      writeKey,
+    });
   }
 
   private shouldSendEvent() {
@@ -44,11 +64,42 @@ export class TelemetryClient {
       return;
     }
 
+    const flattenedProperties = flattenObject(properties);
+    const propertiesWithGlobal = {
+      ...this.globalProperties,
+      ...flattenedProperties,
+    };
+    const orderedPropertiesWithGlobal = Object.keys(propertiesWithGlobal)
+      .sort()
+      .reduce(
+        (obj, key) => {
+          obj[key] = propertiesWithGlobal[key];
+          return obj;
+        },
+        {} as Record<string, any>,
+      );
+
+    if (this.segment) {
+      this.segment.track({
+        anonymousId: this.anonymousId,
+        event,
+        properties: { ...orderedPropertiesWithGlobal },
+      });
+    }
+
     await scarfClient.logEvent({
       event,
     });
   }
 
+  setGlobalProperties(properties: Record<string, any>) {
+    const flattenedProperties = flattenObject(properties);
+    this.globalProperties = {
+      ...this.globalProperties,
+      ...flattenedProperties,
+    };
+  }
+
   private setSampleRate(sampleRate: number | undefined) {
     let _sampleRate: number;
 
@@ -63,6 +114,11 @@ export class TelemetryClient {
     }
 
     this.sampleRate = _sampleRate;
+    this.setGlobalProperties({
+      sampleRate: this.sampleRate,
+      sampleRateAdjustmentFactor: 1 - this.sampleRate,
+      sampleWeight: 1 / this.sampleRate,
+    });
   }
 }
 

package/src/v2/runtime/telemetry/utils.ts

@@ -0,0 +1,15 @@
+export function flattenObject(
+  obj: Record<string, any>,
+  parentKey = "",
+  res: Record<string, any> = {},
+): Record<string, any> {
+  for (const key in obj) {
+    const propName = parentKey ? `${parentKey}.${key}` : key;
+    if (typeof obj[key] === "object" && obj[key] !== null) {
+      flattenObject(obj[key], propName, res);
+    } else {
+      res[propName] = obj[key];
+    }
+  }
+  return res;
+}

package/tsdown.config.ts

@@ -1,7 +1,14 @@
 import { defineConfig } from "tsdown";
 
 export default defineConfig({
-  entry: ["src/index.ts", "src/v2/index.ts", "src/langgraph.ts"],
+  entry: [
+    "src/index.ts",
+    "src/v2/index.ts",
+    "src/v2/express.ts",
+    "src/v2/hono.ts",
+    "src/v2/node.ts",
+    "src/langgraph.ts",
+  ],
   format: ["esm", "cjs"],
   dts: true,
   sourcemap: true,