@copilotkit/runtime 1.55.2-next.1 → 1.55.3-canary.1776215089

package/src/agent/converters/tanstack.ts

@@ -11,24 +11,32 @@ import {
 } from "@ag-ui/client";
 import { randomUUID } from "@copilotkit/shared";
 
+type ContentPartSource =
+  | { type: "data"; value: string; mimeType: string }
+  | { type: "url"; value: string; mimeType?: string };
+
 /**
  * A TanStack AI content part (text, image, audio, video, or document).
  */
 export type TanStackContentPart =
   | { type: "text"; content: string }
-  | {
-      type: "image" | "audio" | "video" | "document";
-      source:
-        | { type: "data"; value: string; mimeType: string }
-        | { type: "url"; value: string; mimeType?: string };
-    };
+  | { type: "image"; source: ContentPartSource }
+  | { type: "audio"; source: ContentPartSource }
+  | { type: "video"; source: ContentPartSource }
+  | { type: "document"; source: ContentPartSource };
 
 /**
  * Message format expected by TanStack AI's `chat()`.
+ *
+ * Content is typed as `any[]` for the multimodal case so messages are directly
+ * passable to any adapter without casts — different adapters constrain which
+ * modalities they accept (e.g. OpenAI only allows text + image).
+ * Use `TanStackContentPart` to inspect individual parts if needed.
  */
 export interface TanStackChatMessage {
   role: "user" | "assistant" | "tool";
-  content: string | null | TanStackContentPart[];
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  content: string | null | any[];
   name?: string;
   toolCalls?: Array<{
     id: string;

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/copilot-runtime.ts

@@ -35,8 +35,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";
 
@@ -318,7 +323,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;
 }
 
 /**

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__/fetch-router.test.ts

@@ -50,6 +50,57 @@ describe("fetch-router", () => {
       expect(result).toBeNull();
     });
 
+    it("matches GET /threads", () => {
+      const result = matchRoute("/api/copilotkit/threads", basePath);
+      expect(result).toEqual({ method: "threads/list" });
+    });
+
+    it("matches POST /threads/subscribe", () => {
+      const result = matchRoute("/api/copilotkit/threads/subscribe", basePath);
+      expect(result).toEqual({ method: "threads/subscribe" });
+    });
+
+    it("matches PATCH /threads/:threadId", () => {
+      const result = matchRoute("/api/copilotkit/threads/thread-abc", basePath);
+      expect(result).toEqual({
+        method: "threads/update",
+        threadId: "thread-abc",
+      });
+    });
+
+    it("matches POST /threads/:threadId/archive", () => {
+      const result = matchRoute(
+        "/api/copilotkit/threads/thread-abc/archive",
+        basePath,
+      );
+      expect(result).toEqual({
+        method: "threads/archive",
+        threadId: "thread-abc",
+      });
+    });
+
+    it("matches GET /threads/:threadId/messages", () => {
+      const result = matchRoute(
+        "/api/copilotkit/threads/thread-abc/messages",
+        basePath,
+      );
+      expect(result).toEqual({
+        method: "threads/messages",
+        threadId: "thread-abc",
+      });
+    });
+
+    it("handles URL-encoded threadId in thread routes", () => {
+      const result = matchRoute(
+        "/api/copilotkit/threads/thread%2F123",
+        basePath,
+      );
+      expect(result).toEqual({
+        method: "threads/update",
+        threadId: "thread/123",
+      });
+    });
+
     it("returns null when basePath is a prefix but not a segment boundary", () => {
       const result = matchRoute("/api/copilotkitextra/info", basePath);
       expect(result).toBeNull();
@@ -124,6 +175,31 @@ describe("fetch-router", () => {
       expect(result).toBeNull();
     });
 
+    it("matches /threads suffix", () => {
+      const result = matchRoute("/anything/threads");
+      expect(result).toEqual({ method: "threads/list" });
+    });
+
+    it("matches /threads/subscribe suffix", () => {
+      const result = matchRoute("/anything/threads/subscribe");
+      expect(result).toEqual({ method: "threads/subscribe" });
+    });
+
+    it("matches /threads/:threadId suffix", () => {
+      const result = matchRoute("/anything/threads/t1");
+      expect(result).toEqual({ method: "threads/update", threadId: "t1" });
+    });
+
+    it("matches /threads/:threadId/archive suffix", () => {
+      const result = matchRoute("/anything/threads/t1/archive");
+      expect(result).toEqual({ method: "threads/archive", threadId: "t1" });
+    });
+
+    it("matches /threads/:threadId/messages suffix", () => {
+      const result = matchRoute("/anything/threads/t1/messages");
+      expect(result).toEqual({ method: "threads/messages", threadId: "t1" });
+    });
+
     it("works with deeply nested mount prefix", () => {
       const result = matchRoute("/api/v2/copilotkit/agent/a1/run");
       expect(result).toEqual({ method: "agent/run", agentId: "a1" });

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

package/src/v2/runtime/core/fetch-handler.ts

@@ -46,6 +46,14 @@ import { handleConnectAgent } from "../handlers/handle-connect";
 import { handleStopAgent } from "../handlers/handle-stop";
 import { handleGetRuntimeInfo } from "../handlers/get-runtime-info";
 import { handleTranscribe } from "../handlers/handle-transcribe";
+import {
+  handleListThreads,
+  handleSubscribeToThreads,
+  handleUpdateThread,
+  handleArchiveThread,
+  handleDeleteThread,
+  handleGetThreadMessages,
+} from "../handlers/handle-threads";
 import {
   parseMethodCall,
   createJsonRequest,
@@ -306,6 +314,31 @@ function dispatchRoute(
       return handleGetRuntimeInfo({ runtime, request });
     case "transcribe":
       return handleTranscribe({ runtime, request });
+    case "threads/list":
+      return handleListThreads({ runtime, request });
+    case "threads/subscribe":
+      return handleSubscribeToThreads({ runtime, request });
+    case "threads/update":
+      if (request.method.toUpperCase() === "DELETE") {
+        return handleDeleteThread({
+          runtime,
+          request,
+          threadId: route.threadId,
+        });
+      }
+      return handleUpdateThread({ runtime, request, threadId: route.threadId });
+    case "threads/archive":
+      return handleArchiveThread({
+        runtime,
+        request,
+        threadId: route.threadId,
+      });
+    case "threads/messages":
+      return handleGetThreadMessages({
+        runtime,
+        request,
+        threadId: route.threadId,
+      });
   }
 }
 
@@ -376,10 +409,28 @@ function validateHttpMethod(
   route: RouteInfo,
 ): Response | null {
   const method = httpMethod.toUpperCase();
-  if (route.method === "info" && method === "GET") return null;
-  if (route.method !== "info" && method === "POST") return null;
-  const allowed = route.method === "info" ? "GET" : "POST";
-  return jsonResponse({ error: "Method not allowed" }, 405, { Allow: allowed });
+
+  switch (route.method) {
+    case "info":
+    case "threads/list":
+    case "threads/messages":
+      if (method === "GET") return null;
+      return jsonResponse({ error: "Method not allowed" }, 405, {
+        Allow: "GET",
+      });
+
+    case "threads/update":
+      if (method === "PATCH" || method === "DELETE") return null;
+      return jsonResponse({ error: "Method not allowed" }, 405, {
+        Allow: "PATCH, DELETE",
+      });
+
+    default:
+      if (method === "POST") return null;
+      return jsonResponse({ error: "Method not allowed" }, 405, {
+        Allow: "POST",
+      });
+  }
 }
 
 /* ------------------------------------------------------------------------------------------------

package/src/v2/runtime/core/fetch-router.ts

@@ -108,5 +108,53 @@ function matchSegments(path: string): RouteInfo | null {
     return { method: "agent/stop", agentId, threadId };
   }
 
+  // /threads/subscribe (2 segments)
+  if (
+    len >= 2 &&
+    segments[len - 2] === "threads" &&
+    segments[len - 1] === "subscribe"
+  ) {
+    return { method: "threads/subscribe" };
+  }
+
+  // /threads/:threadId/messages (3 segments)
+  if (
+    len >= 3 &&
+    segments[len - 3] === "threads" &&
+    segments[len - 1] === "messages"
+  ) {
+    const threadId = safeDecodeURIComponent(segments[len - 2]!);
+    if (!threadId) return null;
+    return { method: "threads/messages", threadId };
+  }
+
+  // /threads/:threadId/archive (3 segments)
+  if (
+    len >= 3 &&
+    segments[len - 3] === "threads" &&
+    segments[len - 1] === "archive"
+  ) {
+    const threadId = safeDecodeURIComponent(segments[len - 2]!);
+    if (!threadId) return null;
+    return { method: "threads/archive", threadId };
+  }
+
+  // /threads/:threadId (2 segments) — update or delete
+  if (
+    len >= 2 &&
+    segments[len - 2] === "threads" &&
+    segments[len - 1] !== "subscribe"
+  ) {
+    const threadId = safeDecodeURIComponent(segments[len - 1]!);
+    if (!threadId) return null;
+    // Disambiguated by HTTP method in the handler
+    return { method: "threads/update", threadId };
+  }
+
+  // /threads (1 segment) — list
+  if (len >= 1 && segments[len - 1] === "threads") {
+    return { method: "threads/list" };
+  }
+
   return null;
 }

package/src/v2/runtime/core/hooks.ts

@@ -38,7 +38,12 @@ export type RouteInfo =
   | { method: "agent/connect"; agentId: string }
   | { method: "agent/stop"; agentId: string; threadId: string }
   | { method: "info" }
-  | { method: "transcribe" };
+  | { method: "transcribe" }
+  | { method: "threads/list" }
+  | { method: "threads/subscribe" }
+  | { method: "threads/update"; threadId: string }
+  | { method: "threads/archive"; threadId: string }
+  | { method: "threads/messages"; threadId: string };
 
 /* ------------------------------------------------------------------------------------------------
  * Hook contexts