+
+
+
+
+
+
+
+ Loading threads...
;
+ if (error) return Error: {error.message}
;
+
+ return (
+
+
+ );
+}
+```
+
+### Deleting Threads
+
+The `deleteThread` method provides optimistic updates with automatic rollback:
+
+```tsx
+const { deleteThread } = useThreads();
+
+// 1. Immediate UI update (thread removed from list)
+// 2. API request sent to server
+// 3. Success: List refreshed for consistency
+// 4. Failure: Thread restored to original position
+await deleteThread(threadId);
+```
+
+**Features:**
+- Instant UI feedback
+- Automatic rollback on error
+- No manual URL construction needed
+- Proper error handling
+
+## Core API
+
+### deleteThread
+
+Delete a thread using the core helper method:
+
+```tsx
+import { useCopilotKit } from "@copilotkitnext/react";
+
+function CustomThreadManager() {
+ const { copilotkit } = useCopilotKit();
+
+ const deleteThread = async (threadId: string) => {
+ try {
+ await copilotkit.deleteThread(threadId);
+ console.log("Thread deleted successfully");
+ } catch (error) {
+ if (error.message.includes("Not Found")) {
+ console.log("Thread doesn't exist");
+ } else if (error.message.includes("Forbidden")) {
+ console.log("No permission to delete");
+ } else {
+ console.error("Delete failed:", error);
+ }
+ }
+ };
+}
+```
+
+**Benefits:**
+- No manual URL construction
+- Automatic header and resource ID inclusion
+- Consistent error handling
+- Cleaner, more maintainable code
+
+## External State Management
+
+### React Query Integration
+
+```tsx
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
+import { CopilotThreadList, useThreads } from "@copilotkitnext/react";
+
+function ThreadListWithReactQuery() {
+ const queryClient = useQueryClient();
+ const { deleteThread } = useThreads();
+
+ // React Query handles fetching and caching
+ const { data, refetch } = useQuery({
+ queryKey: ['threads'],
+ queryFn: fetchThreads,
+ refetchInterval: 3000, // React Query controls refresh
+ });
+
+ const deleteMutation = useMutation({
+ mutationFn: deleteThread,
+ onSuccess: () => {
+ // Invalidate to trigger refetch
+ queryClient.invalidateQueries(['threads']);
+ },
+ });
+
+ return (
+ Your Conversations ({total})
+ {threads.map((thread) => ( +
+
+ ))}
+ {thread.firstMessage || "New conversation"}
+{thread.messageCount} messages
+ +
+
+
+ );
+}
+```
+
+## Switching Between Threads
+
+CopilotChat automatically handles thread switching when the `threadId` prop changes:
+
+```tsx
+function MultiThreadChat() {
+ const [currentThread, setCurrentThread] = useState("thread-1");
+ const { threads } = useThreads();
+
+ return (
+
+ {/* Thread selector */}
+
+
+ {/* Chat will automatically load the selected thread */}
+
+ );
+}
+```
+
+## Customizing the Thread List
+
+### Custom Thread Renderer
+
+```tsx
+
+
+
+
+ )}
+/>
+```
+
+### Custom Empty State
+
+```tsx
+import { randomUUID } from "@copilotkitnext/shared";
+import { CopilotThreadList, useThreads, useCopilotChatConfiguration } from "@copilotkitnext/react";
+
+function ThreadListWithEmptyState() {
+ const { threads, isLoading } = useThreads();
+ const config = useCopilotChatConfiguration();
+
+ if (isLoading) {
+ return Loading threads…
;
+ }
+
+ if (threads.length === 0) {
+ return (
+
+
+ );
+ }
+
+ return No conversations yet
+ +
+ {threads.map(thread => (
+
+ );
+}
+```
+
+### Pagination
+
+```tsx
+function PaginatedThreadList() {
+ const [offset, setOffset] = useState(0);
+ const limit = 20;
+ const { threads, total, fetchThreads } = useThreads({ limit });
+
+ const handleNextPage = () => {
+ const newOffset = offset + limit;
+ setOffset(newOffset);
+ fetchThreads(newOffset);
+ };
+
+ const handlePrevPage = () => {
+ const newOffset = Math.max(0, offset - limit);
+ setOffset(newOffset);
+ fetchThreads(newOffset);
+ };
+
+ return (
+
+ {thread.firstMessage || "Untitled"}
+
+
+ ))}
+
+
+ );
+}
+```
+
+## Backend Configuration
+
+Thread storage is handled automatically by the AgentRunner. Choose the appropriate runner for your deployment:
+
+### In-Memory (Development)
+
+```typescript
+import { CopilotRuntime, InMemoryAgentRunner } from "@copilotkitnext/runtime";
+
+const runtime = new CopilotRuntime({
+ agents: myAgents,
+ runner: new InMemoryAgentRunner(), // Default
+});
+```
+
+### SQLite (Single Server)
+
+```typescript
+import { SqliteAgentRunner } from "@copilotkitnext/runtime";
+
+const runtime = new CopilotRuntime({
+ agents: myAgents,
+ runner: new SqliteAgentRunner({
+ dbPath: "./copilot.db", // Persistent storage
+ }),
+});
+```
+
+### Enterprise (Multi-Server with Redis)
+
+```typescript
+import { EnterpriseAgentRunner } from "@copilotkitnext/runtime";
+import { Kysely } from "kysely";
+import Redis from "ioredis";
+
+const runtime = new CopilotRuntime({
+ agents: myAgents,
+ runner: new EnterpriseAgentRunner({
+ kysely: new Kysely({
+ // Your database config
+ }),
+ redis: new Redis({
+ // Your Redis config
+ }),
+ }),
+});
+```
+
+## API Reference
+
+### CopilotThreadList Component
+
+```typescript
+interface CopilotThreadListProps {
+ limit?: number; // Default: 50
+ onThreadSelect?: (threadId: string) => void;
+ className?: string;
+ refreshInterval?: number; // Default: 2000 (ms)
+ disableAutoRefresh?: boolean; // Default: false
+ threadItem?: SlotValue;
+ newThreadButton?: SlotValue;
+ container?: SlotValue;
+}
+```
+
+### useThreads Hook
+
+```typescript
+interface UseThreadsOptions {
+ limit?: number; // Default: 50
+ autoFetch?: boolean; // Default: true
+}
+
+interface UseThreadsResult {
+ threads: ThreadMetadata[];
+ total: number;
+ isLoading: boolean;
+ error: Error | null;
+ fetchThreads: (offset?: number) => Promise
+
+
+ Showing {offset + 1}-{Math.min(offset + limit, total)} of {total}
+
+
+
+
+
+
+
+
+
+
+
+
+ )}
+/>
+```
+
+Props passed to custom renderer:
+
+```typescript
+interface ThreadListItemProps {
+ thread: ThreadMetadata;
+ isActive?: boolean;
+ onClick?: () => void;
+ onDelete?: () => void;
+}
+```
+
+### newThreadButton
+
+`SlotValue
+ {children}
+
+ )}
+/>
+```
+
+## Examples
+
+### Custom Refresh Intervals
+
+```tsx
+// Fast refresh for real-time updates
+
+
+
+
+ )}
+/>
+```
+
+### Custom Empty State
+
+```tsx
+import { useThreads, useCopilotChatConfiguration } from "@copilotkitnext/react";
+import { randomUUID } from "@copilotkitnext/shared";
+
+function ThreadListWithEmptyState() {
+ const { threads, isLoading } = useThreads();
+ const config = useCopilotChatConfiguration();
+
+ if (isLoading) return Loading...
;
+
+ if (threads.length === 0) {
+ return (
+
+
+ );
+ }
+
+ return No conversations yet
+ +Loading...
;
+ if (error) return Error: {error.message}
;
+
+ return (
+
+ {threads.map(thread => (
+
+ );
+}
+```
+
+## Options
+
+### limit
+
+`number` **(optional, default: 50)**
+
+Maximum number of threads to fetch per request.
+
+```tsx
+const { threads } = useThreads({ limit: 20 });
+```
+
+### autoFetch
+
+`boolean` **(optional, default: true)**
+
+Whether to automatically fetch threads when the component mounts.
+
+```tsx
+const { threads, fetchThreads } = useThreads({ autoFetch: false });
+```
+
+## Return Value
+
+### threads
+
+`ThreadMetadata[]`
+
+Array of thread metadata objects.
+
+```typescript
+interface ThreadMetadata {
+ threadId: string;
+ createdAt: number;
+ lastActivityAt: number;
+ isRunning: boolean;
+ messageCount: number;
+ firstMessage?: string;
+}
+```
+
+### total
+
+`number`
+
+Total number of threads available.
+
+### isLoading
+
+`boolean`
+
+Loading state for fetch operations.
+
+### error
+
+`Error | null`
+
+Error state if fetch operations fail.
+
+### fetchThreads
+
+`(offset?: number) => Promise
+
+ ))}
+ {thread.firstMessage || "New conversation"}
+{thread.messageCount} messages
+
+
+ {threads.map(thread => (
+
+ );
+}
+```
+
+### With Pagination
+
+```tsx
+import { useState } from "react";
+
+function PaginatedThreads() {
+ const [offset, setOffset] = useState(0);
+ const limit = 20;
+ const { threads, total, fetchThreads } = useThreads({ limit });
+
+ const nextPage = () => {
+ const newOffset = offset + limit;
+ setOffset(newOffset);
+ fetchThreads(newOffset);
+ };
+
+ const prevPage = () => {
+ const newOffset = Math.max(0, offset - limit);
+ setOffset(newOffset);
+ fetchThreads(newOffset);
+ };
+
+ return (
+ {thread.firstMessage}
+ ))}
+
+ {threads.map(thread => (
+
+ );
+}
+```
+
+### Delete with Confirmation
+
+```tsx
+function ThreadManager() {
+ const { threads, deleteThread } = useThreads();
+
+ const handleDelete = async (threadId: string, name: string) => {
+ if (!window.confirm(`Delete "${name}"?`)) return;
+
+ try {
+ await deleteThread(threadId);
+ } catch (error) {
+ alert("Failed to delete thread");
+ }
+ };
+
+ return (
+ {thread.firstMessage}
+ ))}
+
+
+
+ Showing {offset + 1}-{Math.min(offset + limit, total)} of {total}
+
+
+
+
+ {threads.map(thread => (
+
+ );
+}
+```
+
+### Auto-Switch After Delete
+
+```tsx
+import { useCopilotChatConfiguration } from "@copilotkitnext/react";
+
+function ThreadManager() {
+ const config = useCopilotChatConfiguration();
+ const { threads, deleteThread } = useThreads();
+
+ const handleDelete = async (threadId: string) => {
+ await deleteThread(threadId);
+
+ // Switch to another thread if deleted the active one
+ if (threadId === config?.threadId && threads.length > 0) {
+ config?.setThreadId(threads[0].threadId);
+ }
+ };
+
+ return (
+
+ {thread.firstMessage || "Untitled"}
+
+
+ ))}
+
+ {threads.map(thread => (
+
+ );
+}
+```
+
+### With External State Management
+
+```tsx
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
+
+function ThreadListWithReactQuery() {
+ const queryClient = useQueryClient();
+ const { threads, deleteThread } = useThreads();
+
+ const deleteMutation = useMutation({
+ mutationFn: deleteThread,
+ onSuccess: () => {
+ queryClient.invalidateQueries(['threads']);
+ queryClient.invalidateQueries(['messages']);
+ },
+ });
+
+ return (
+
+ {thread.firstMessage}
+
+
+ ))}
+
+ {threads.map(thread => (
+
+ );
+}
+```
+
+## Related
+
+- [Thread Management Guide](/guides/thread-management)
+- [CopilotThreadList Component](/reference/copilot-thread-list)
+- [CopilotChatConfigurationProvider](/reference/copilot-chat-configuration-provider)
diff --git a/apps/react/demo/src/app/api/copilotkit/[[...slug]]/route.ts b/apps/react/demo/src/app/api/copilotkit/[[...slug]]/route.ts
index f4b3e29c..a5e3e278 100644
--- a/apps/react/demo/src/app/api/copilotkit/[[...slug]]/route.ts
+++ b/apps/react/demo/src/app/api/copilotkit/[[...slug]]/route.ts
@@ -5,14 +5,14 @@ import { BasicAgent } from "@copilotkitnext/agent";
// Determine which model to use based on available API keys
const getModelConfig = () => {
if (process.env.OPENAI_API_KEY?.trim()) {
- return "openai/gpt-4o";
+ return "openai/gpt-4o-mini";
} else if (process.env.ANTHROPIC_API_KEY?.trim()) {
return "anthropic/claude-sonnet-4.5";
} else if (process.env.GOOGLE_API_KEY?.trim()) {
return "google/gemini-2.5-pro";
}
// Default to OpenAI (will fail at runtime if no key is set)
- return "openai/gpt-4o";
+ return "openai/gpt-4o-mini";
};
const agent = new BasicAgent({
@@ -26,6 +26,27 @@ const runtime = new CopilotRuntime({
default: agent,
},
runner: new InMemoryAgentRunner(),
+ // Resource scoping: Control which threads each user can access
+ // Security note: In production, authenticate via session cookies, JWTs, etc.
+ // The client declares which user they are (x-user-id header), but YOU must
+ // validate this against your auth system. This demo simulates that validation.
+ resolveThreadsScope: async ({ request }) => {
+ const userId = request.headers.get("x-user-id");
+ const isAdmin = request.headers.get("x-is-admin") === "true";
+
+ // Admin bypass: sees all threads across all users
+ if (isAdmin) {
+ return null; // null = no filtering (admin access)
+ }
+
+ // Regular user: only sees their own threads
+ // In production: const userId = await authenticateUser(request);
+ return {
+ resourceId: userId || "anonymous",
+ };
+ },
+ // Suppress warnings for demo purposes
+ suppressResourceIdWarning: true,
});
const app = createCopilotEndpoint({
@@ -35,3 +56,4 @@ const app = createCopilotEndpoint({
export const GET = handle(app);
export const POST = handle(app);
+export const DELETE = handle(app);
diff --git a/apps/react/demo/src/app/page.tsx b/apps/react/demo/src/app/page.tsx
index a6107430..0b62b6f5 100644
--- a/apps/react/demo/src/app/page.tsx
+++ b/apps/react/demo/src/app/page.tsx
@@ -1,20 +1,29 @@
"use client";
import {
- CopilotChat,
CopilotKitProvider,
useFrontendTool,
defineToolCallRenderer,
- useConfigureSuggestions,
+ CopilotSidebar,
+ CopilotChat,
} from "@copilotkitnext/react";
import type { ToolsMenuItem } from "@copilotkitnext/react";
import { z } from "zod";
-import { useMemo } from "react";
+import { useMemo, useState } from "react";
// Disable static optimization for this page
export const dynamic = "force-dynamic";
+// Simulated users for demo
+const DEMO_USERS = [
+ { id: "user-alice", name: "Alice 👩", color: "bg-blue-100 border-blue-400" },
+ { id: "user-bob", name: "Bob 👨", color: "bg-green-100 border-green-400" },
+ { id: "user-charlie", name: "Charlie 🧑", color: "bg-purple-100 border-purple-400" },
+ { id: "admin", name: "Admin 👑 (null scope)", color: "bg-red-100 border-red-400" },
+];
+
export default function Home() {
+ const [currentUser, setCurrentUser] = useState(DEMO_USERS[0]);
// Define a wildcard renderer for any undefined tools
const wildcardRenderer = defineToolCallRenderer({
name: "*",
@@ -39,18 +48,56 @@ export default function Home() {
});
return (
-
+ {thread.firstMessage}
+
+
+ ))}
+
-
+
+
+ Demo User:
+
+
+ {DEMO_USERS.map((user) => (
+
+ ))}
+
+
+ Resource ID: {currentUser.id === "admin" ? "null (sees all)" : currentUser.id}
+
+
+ 💡 Try this: Create threads as Alice, then switch to Bob - you won't see Alice's
+ threads! Admin can see all threads. This demonstrates resource scoping for multi-tenant apps.
+
+
+
+
+ );
+
+ // Approach 1b: Using CopilotSidebar with thread list button
+ // Uncomment below to see the modal sidebar with thread list button:
+ /*
+ return (
+
+
+
+
+ );
+ */
}
diff --git a/packages/core/src/__tests__/core-delete-thread.test.ts b/packages/core/src/__tests__/core-delete-thread.test.ts
new file mode 100644
index 00000000..3ae2811d
--- /dev/null
+++ b/packages/core/src/__tests__/core-delete-thread.test.ts
@@ -0,0 +1,347 @@
+import { describe, it, expect, beforeEach, vi, afterEach } from "vitest";
+import { CopilotKitCore } from "../core";
+
+describe("CopilotKitCore - deleteThread", () => {
+ let copilotKitCore: CopilotKitCore;
+ let mockFetch: ReturnType
+
+ {threads.map(({ firstMessage, threadId }) => (
+
+ switchThread(threadId)}
+ className={`p-3 rounded-lg cursor-pointer transition ${
+ threadId === currentThreadId
+ ? "bg-blue-100 border-2 border-blue-500"
+ : "bg-gray-100 hover:bg-gray-200"
+ }`}
+ >
+ {firstMessage || "New conversation"}
+
+ ))}
+
{BoundAddMenuButton}
@@ -1017,7 +1006,9 @@ export namespace CopilotChatInput {
Add files and more
- /
+
+ /
+
-
+
@@ -101,9 +119,71 @@ export namespace CopilotModalHeader {
);
+
+ export interface LeftContentProps {
+ onThreadListClick?: () => void;
+ showThreadListButton?: boolean;
+ onNewThreadClick?: () => void;
+ showNewThreadButton?: boolean;
+ className?: string;
+ children?: React.ReactNode;
+ }
+
+ export const LeftContent: React.FC{BoundLeftContent}
{BoundTitle}
{BoundCloseButton}
{children}
;
+ }
+
+ const hasAnyButton = (showNewThreadButton && onNewThreadClick) || (showThreadListButton && onThreadListClick);
+
+ if (!hasAnyButton) {
+ return null;
+ }
+
+ return (
+
+ {showNewThreadButton && onNewThreadClick && (
+
+ )}
+ {showThreadListButton && onThreadListClick && (
+
+ )}
+
+ );
+ };
}
CopilotModalHeader.Title.displayName = "CopilotModalHeader.Title";
CopilotModalHeader.CloseButton.displayName = "CopilotModalHeader.CloseButton";
+CopilotModalHeader.LeftContent.displayName = "CopilotModalHeader.LeftContent";
export default CopilotModalHeader;
diff --git a/packages/react/src/components/chat/CopilotPopup.tsx b/packages/react/src/components/chat/CopilotPopup.tsx
index 55ec4947..efdd871c 100644
--- a/packages/react/src/components/chat/CopilotPopup.tsx
+++ b/packages/react/src/components/chat/CopilotPopup.tsx
@@ -10,6 +10,8 @@ export type CopilotPopupProps = Omit
+
+
{headerElement}
+
+
{headerElement}
diff --git a/packages/react/src/components/chat/__tests__/CopilotChat.e2e.test.tsx b/packages/react/src/components/chat/__tests__/CopilotChat.e2e.test.tsx
index 160a1b4b..6411fb79 100644
--- a/packages/react/src/components/chat/__tests__/CopilotChat.e2e.test.tsx
+++ b/packages/react/src/components/chat/__tests__/CopilotChat.e2e.test.tsx
@@ -1,5 +1,5 @@
import React, { useEffect } from "react";
-import { screen, fireEvent, waitFor } from "@testing-library/react";
+import { screen, fireEvent, waitFor, act } from "@testing-library/react";
import { z } from "zod";
import { defineToolCallRenderer, ReactToolCallRenderer } from "@/types";
import {
@@ -16,6 +16,7 @@ import {
} from "@/__tests__/utils/test-helpers";
import { useConfigureSuggestions } from "@/hooks/use-configure-suggestions";
import { CopilotChat } from "../CopilotChat";
+import { EventType } from "@ag-ui/core";
describe("CopilotChat E2E - Chat Basics and Streaming Patterns", () => {
describe("Chat Basics: text input + run", () => {
@@ -65,26 +66,26 @@ describe("CopilotChat E2E - Chat Basics and Streaming Patterns", () => {
const messageId = testId("msg");
agent.emit(runStartedEvent());
-
+
// Stream text progressively
agent.emit(textChunkEvent(messageId, "Once upon"));
-
+
await waitFor(() => {
expect(screen.getByText(/Once upon/)).toBeDefined();
});
-
+
agent.emit(textChunkEvent(messageId, " a time"));
-
+
await waitFor(() => {
expect(screen.getByText(/Once upon a time/)).toBeDefined();
});
-
+
agent.emit(textChunkEvent(messageId, " there was a robot."));
-
+
await waitFor(() => {
expect(screen.getByText(/Once upon a time there was a robot\./)).toBeDefined();
});
-
+
agent.emit(runFinishedEvent());
agent.complete();
});
@@ -102,7 +103,7 @@ describe("CopilotChat E2E - Chat Basics and Streaming Patterns", () => {
}),
render: ({ name, args, result, status }) => (
[];
@@ -410,12 +427,14 @@ describe("CopilotChat E2E - Chat Basics and Streaming Patterns", () => {
agent.emit(runStartedEvent());
// Emit tool call WITHOUT any text content
- agent.emit(toolCallChunkEvent({
- toolCallId,
- toolCallName: "testTool",
- parentMessageId: messageId,
- delta: '{"value":"test"}',
- }));
+ agent.emit(
+ toolCallChunkEvent({
+ toolCallId,
+ toolCallName: "testTool",
+ parentMessageId: messageId,
+ delta: '{"value":"test"}',
+ }),
+ );
// Tool call should be rendered
await waitFor(() => {
@@ -431,7 +450,9 @@ describe("CopilotChat E2E - Chat Basics and Streaming Patterns", () => {
if (assistantMessageDiv) {
// Check that within the assistant message, there's no copy button
- const copyButtonsInAssistant = assistantMessageDiv.querySelectorAll("button[aria-label*='Copy' i], button[aria-label*='copy' i]");
+ const copyButtonsInAssistant = assistantMessageDiv.querySelectorAll(
+ "button[aria-label*='Copy' i], button[aria-label*='copy' i]",
+ );
expect(copyButtonsInAssistant.length).toBe(0);
}
});
@@ -447,9 +468,7 @@ describe("CopilotChat E2E - Chat Basics and Streaming Patterns", () => {
// Should now have copy button
const toolbarButtons = screen.getAllByRole("button");
- const copyButton = toolbarButtons.find(btn =>
- btn.getAttribute("aria-label")?.toLowerCase().includes("copy")
- );
+ const copyButton = toolbarButtons.find((btn) => btn.getAttribute("aria-label")?.toLowerCase().includes("copy"));
expect(copyButton).toBeDefined();
});
@@ -463,20 +482,12 @@ describe("CopilotChat E2E - Chat Basics and Streaming Patterns", () => {
defineToolCallRenderer({
name: "specificTool",
args: z.object({ value: z.string() }),
- render: ({ args }) => (
- [];
@@ -497,22 +508,26 @@ describe("CopilotChat E2E - Chat Basics and Streaming Patterns", () => {
const toolCallId2 = testId("tc2");
agent.emit(runStartedEvent());
-
+
// Call the specific tool
- agent.emit(toolCallChunkEvent({
- toolCallId: toolCallId1,
- toolCallName: "specificTool",
- parentMessageId: messageId,
- delta: '{"value":"test123"}',
- }));
+ agent.emit(
+ toolCallChunkEvent({
+ toolCallId: toolCallId1,
+ toolCallName: "specificTool",
+ parentMessageId: messageId,
+ delta: '{"value":"test123"}',
+ }),
+ );
// Call an unknown tool
- agent.emit(toolCallChunkEvent({
- toolCallId: toolCallId2,
- toolCallName: "unknownTool",
- parentMessageId: messageId,
- delta: '{"data":"xyz"}',
- }));
+ agent.emit(
+ toolCallChunkEvent({
+ toolCallId: toolCallId2,
+ toolCallName: "unknownTool",
+ parentMessageId: messageId,
+ delta: '{"data":"xyz"}',
+ }),
+ );
// Specific renderer should be used for specificTool
await waitFor(() => {
@@ -619,10 +634,13 @@ describe("CopilotChat E2E - Chat Basics and Streaming Patterns", () => {
});
// Verify suggestions appear (provider agent's run() method will be called automatically)
- await waitFor(() => {
- expect(screen.getByText("Option A")).toBeDefined();
- expect(screen.getByText("Option B")).toBeDefined();
- }, { timeout: 5000 });
+ await waitFor(
+ () => {
+ expect(screen.getByText("Option A")).toBeDefined();
+ expect(screen.getByText("Option B")).toBeDefined();
+ },
+ { timeout: 5000 },
+ );
// Click on a suggestion
const suggestionA = screen.getByText("Option A");
@@ -687,10 +705,13 @@ describe("CopilotChat E2E - Chat Basics and Streaming Patterns", () => {
consumerAgent.complete();
// Verify both suggestions are visible after streaming completes
- await waitFor(() => {
- expect(screen.getByText("First Action")).toBeDefined();
- expect(screen.getByText("Second Action")).toBeDefined();
- }, { timeout: 5000 });
+ await waitFor(
+ () => {
+ expect(screen.getByText("First Action")).toBeDefined();
+ expect(screen.getByText("Second Action")).toBeDefined();
+ },
+ { timeout: 5000 },
+ );
});
it("should handle multiple suggestions streaming concurrently", async () => {
@@ -748,11 +769,151 @@ describe("CopilotChat E2E - Chat Basics and Streaming Patterns", () => {
consumerAgent.complete();
// Verify all suggestions appear
+ await waitFor(
+ () => {
+ expect(screen.getByText("Alpha")).toBeDefined();
+ expect(screen.getByText("Beta")).toBeDefined();
+ expect(screen.getByText("Gamma")).toBeDefined();
+ },
+ { timeout: 5000 },
+ );
+ });
+ });
+
+ describe("Thread Switching", () => {
+ it("should clear messages when switching threads", async () => {
+ const agent = new MockStepwiseAgent();
+ renderWithCopilotKit({ agent, threadId: "thread-A" });
+
+ // Wait for component to set agent threadId to thread-A
await waitFor(() => {
- expect(screen.getByText("Alpha")).toBeDefined();
- expect(screen.getByText("Beta")).toBeDefined();
- expect(screen.getByText("Gamma")).toBeDefined();
- }, { timeout: 5000 });
+ expect(agent.threadId).toBe("thread-A");
+ });
+
+ // Manually add messages to simulate having messages on thread A
+ agent.messages.push({
+ id: testId("msg-1"),
+ role: "user",
+ content: "User message on A",
+ });
+ agent.messages.push({
+ id: testId("msg-2"),
+ role: "assistant",
+ content: "Assistant response on A",
+ });
+
+ // Verify messages exist in the agent
+ expect(agent.messages.length).toBe(2);
+
+ // Now switch to a different thread by creating a new render
+ const { unmount } = renderWithCopilotKit({ agent, threadId: "thread-B" });
+
+ // Wait for thread switch to complete
+ await waitFor(() => {
+ expect(agent.threadId).toBe("thread-B");
+ });
+
+ // Messages should be cleared, then connectAgent() would sync thread-B's messages from backend
+ // In this test with MockStepwiseAgent, there's no backend, so messages stay at 0
+ expect(agent.messages.length).toBe(0);
+
+ unmount();
+ });
+
+ it("should only show messages when agent threadId matches expected thread", async () => {
+ const agent = new MockStepwiseAgent();
+ renderWithCopilotKit({ agent, threadId: "thread-A" });
+
+ // Wait for initial thread setup
+ await waitFor(() => {
+ expect(agent.threadId).toBe("thread-A");
+ });
+
+ // Add a message when on correct thread
+ agent.messages.push({
+ id: testId("msg-a"),
+ role: "assistant",
+ content: "Message A",
+ });
+
+ // Simulate agent being on wrong thread (race condition scenario)
+ agent.threadId = "thread-B";
+
+ // Wait a bit
+ await new Promise((resolve) => setTimeout(resolve, 50));
+
+ // The component expects thread-A, but agent is on thread-B
+ // So filtering should prevent the message from being displayed
+ // (This tests the safeMessages filter logic)
+ const messageElements = screen.queryAllByText(/Message A/);
+
+ // Message should not be visible because threadIds don't match
+ expect(messageElements.length).toBe(0);
+ });
+
+ it("should allow reconnection to original thread after aborted switch", async () => {
+ // This test verifies the fix for P1 bug: switching from A -> B -> A rapidly
+ // would leave the chat permanently disconnected from A.
+ //
+ // Bug scenario:
+ // 1. Start on thread A (previousThreadIdRef = "thread-A")
+ // 2. Switch to B: disconnect from A succeeds, but before connect to B completes...
+ // 3. Switch back to A: the A->B switch is aborted
+ // 4. Without the fix: previousThreadIdRef is still "thread-A", so the guard at
+ // line 66 (previousThreadIdRef.current === resolvedThreadId) returns early
+ // and we never reconnect to A. Chat stays blank.
+ // 5. With the fix: previousThreadIdRef is reset to null on abort, so the guard
+ // allows reconnection.
+ const agent = new MockStepwiseAgent();
+
+ // Create a wrapper component that controls threadId with state
+ function TestWrapper() {
+ const [currentThreadId, setCurrentThreadId] = React.useState("thread-A");
+
+ // Expose the setter for tests
+ React.useEffect(() => {
+ (window as any).setThreadId = setCurrentThreadId;
+ }, []);
+
+ return ;
+
+ /**
+ * Slot for customizing the new thread button
+ */
+ newThreadButton?: SlotValue;
+
+ /**
+ * Slot for customizing the container
+ */
+ container?: SlotValue;
+
+ /**
+ * Interval in milliseconds for auto-refreshing threads when a thread is running or unnamed.
+ * @default 2000
+ */
+ refreshInterval?: number;
+
+ /**
+ * Disable automatic polling/refresh of threads.
+ * Use this when you have external invalidation mechanisms (e.g., React Query, SWR).
+ * @default false
+ */
+ disableAutoRefresh?: boolean;
+}
+
+function CopilotThreadListInner({
+ limit = 50,
+ onThreadSelect,
+ className,
+ threadItem,
+ newThreadButton,
+ container,
+ refreshInterval = 2000,
+ disableAutoRefresh = false,
+}: CopilotThreadListProps) {
+ const config = useCopilotChatConfiguration();
+ const { threads, isLoading, error, fetchThreads, addOptimisticThread, refresh, currentThreadId, deleteThread } =
+ useThreads({
+ limit,
+ });
+
+ // Track which threads we've already attempted to fetch to prevent infinite loops
+ const attemptedFetchRef = useRef>(new Set());
+
+ const handleNewThread = useCallback(() => {
+ const newThreadId = randomUUID();
+ addOptimisticThread(newThreadId);
+ config?.setThreadId?.(newThreadId);
+ onThreadSelect?.(newThreadId);
+ }, [addOptimisticThread, config, onThreadSelect]);
+
+ const handleThreadSelect = useCallback(
+ (threadId: string) => {
+ config?.setThreadId?.(threadId);
+ onThreadSelect?.(threadId);
+ },
+ [config, onThreadSelect],
+ );
+
+ const handleDeleteThread = useCallback(
+ async (threadId: string) => {
+ try {
+ await deleteThread(threadId);
+ // If the deleted thread was active, create a new thread
+ if (threadId === (currentThreadId ?? config?.threadId)) {
+ const newThreadId = randomUUID();
+ addOptimisticThread(newThreadId);
+ config?.setThreadId?.(newThreadId);
+ }
+ } catch (err) {
+ console.error("Failed to delete thread:", err);
+ }
+ },
+ [deleteThread, currentThreadId, config, addOptimisticThread],
+ );
+
+ // Refresh when current thread is not in the list (e.g., after creating via header button)
+ useEffect(() => {
+ const activeId = currentThreadId ?? config?.threadId;
+ if (!activeId) return;
+
+ const isCurrentThreadInList = threads.some((t) => t.threadId === activeId);
+
+ if (isCurrentThreadInList) {
+ // Thread found - clear from attempted set so we can retry if it's removed later
+ attemptedFetchRef.current.delete(activeId);
+ return;
+ }
+
+ // Thread not in list - check if we should refresh
+ if (!isLoading && !attemptedFetchRef.current.has(activeId)) {
+ // Mark as attempted before calling refresh to prevent immediate re-trigger
+ attemptedFetchRef.current.add(activeId);
+ refresh();
+ }
+ }, [currentThreadId, config?.threadId, threads, refresh, isLoading]);
+
+ // Refresh threads periodically if a thread is running or has no firstMessage yet
+ useEffect(() => {
+ // Skip auto-refresh if disabled
+ if (disableAutoRefresh) return;
+
+ const hasRunningThread = threads.some((t) => t.isRunning);
+ const hasUnnamedThread = threads.some((t) => !t.firstMessage);
+
+ if (!hasRunningThread && !hasUnnamedThread) return;
+
+ const interval = setInterval(() => {
+ refresh();
+ }, refreshInterval);
+
+ return () => clearInterval(interval);
+ }, [threads, refresh, refreshInterval, disableAutoRefresh]);
+
+ const BoundNewThreadButton = renderSlot(newThreadButton, NewThreadButton, {
+ onClick: handleNewThread,
+ });
+
+ const activeThreadId = currentThreadId ?? config?.threadId;
+
+ const threadItems = threads.map((thread) => {
+ const isActive = thread.threadId === activeThreadId;
+ return renderSlot(threadItem, ThreadListItem, {
+ key: thread.threadId,
+ thread,
+ isActive,
+ onClick: () => handleThreadSelect(thread.threadId),
+ onDelete: () => handleDeleteThread(thread.threadId),
+ });
+ });
+
+ const content = (
+ <>
+ {BoundNewThreadButton}
+ > = ({ className, children, ...props }) => (
+ > = ({ className, ...props }) => (
+
+);
+
+export interface ThreadListItemProps {
+ thread: ThreadMetadata;
+ isActive?: boolean;
+ onClick?: () => void;
+ onDelete?: () => void;
+}
+
+const ThreadListItem: React.FC = ({ thread, isActive, onClick, onDelete }) => {
+ const displayText = thread.firstMessage?.substring(0, 60) || "New conversation";
+ const hasEllipsis = thread.firstMessage && thread.firstMessage.length > 60;
+ const messageCount = thread.messageCount || 0;
+ const [isDeleting, setIsDeleting] = useState(false);
+
+ const handleDelete = useCallback(
+ async (e: React.MouseEvent) => {
+ e.stopPropagation(); // Prevent thread selection when clicking delete
+ if (!onDelete) return;
+
+ setIsDeleting(true);
+ try {
+ await onDelete();
+ } catch (err) {
+ console.error("Delete failed:", err);
+ setIsDeleting(false);
+ }
+ },
+ [onDelete],
+ );
+
+ return (
+
+
+ );
+ }
+
+ // Otherwise, use the existing provider
+ return {children}
+ );
+
+ it("should render with default refresh interval", () => {
+ mockThreads.mockReturnValue([
+ {
+ threadId: "thread-1",
+ createdAt: Date.now(),
+ lastActivityAt: Date.now(),
+ isRunning: true,
+ messageCount: 3,
+ firstMessage: "Hello",
+ },
+ ]);
+
+ const { container } = render({children}
+ ),
+ });
+
+ expect(result.current.switchThread).toBeDefined();
+ expect(typeof result.current.switchThread).toBe("function");
+ expect(result.current.currentThreadId).toBeDefined();
+ });
+
+ it("returns current thread ID from config", () => {
+ const { result } = renderHook(() => useThreadSwitch(), {
+ wrapper: ({ children }: { children: ReactNode }) => (
+ {children}
+ ),
+ });
+
+ expect(result.current.currentThreadId).toBe("my-thread");
+ });
+
+ it("updates thread ID when switchThread is called", () => {
+ const { result } = renderHook(() => useThreadSwitch(), {
+ wrapper: ({ children }: { children: ReactNode }) => (
+ {children}
+ ),
+ });
+
+ const initialThreadId = result.current.currentThreadId;
+ expect(initialThreadId).toBeDefined();
+
+ // Switch to a new thread
+ act(() => {
+ result.current.switchThread("new-thread-id");
+ });
+
+ // The thread ID should now be updated
+ expect(result.current.currentThreadId).toBe("new-thread-id");
+ });
+
+ it("works without a configuration provider", () => {
+ const { result } = renderHook(() => useThreadSwitch());
+
+ // Should not crash when no config provider exists
+ expect(result.current.switchThread).toBeDefined();
+ expect(result.current.currentThreadId).toBeUndefined();
+
+ // Calling switchThread should not crash (it just won't do anything)
+ act(() => {
+ result.current.switchThread("thread-x");
+ });
+
+ // Thread ID should still be undefined since there's no provider
+ expect(result.current.currentThreadId).toBeUndefined();
+ });
+
+ describe("Race Conditions", () => {
+ it("should handle rapid thread ID changes without showing stale messages", async () => {
+ // This test documents the expected behavior for rapid thread switching
+ // In a real implementation:
+ // - Rapid switches should cancel in-flight requests
+ // - Only messages from the final thread should be shown
+ // - No stale data from intermediate threads should appear
+
+ const { result } = renderHook(() => useThreadSwitch(), {
+ wrapper: ({ children }: { children: ReactNode }) => (
+ {children}
+ ),
+ });
+
+ const initialThreadId = result.current.currentThreadId;
+
+ // Switch to thread-1 first
+ act(() => {
+ result.current.switchThread("thread-1");
+ });
+
+ // Rapidly switch between threads
+ act(() => {
+ result.current.switchThread("thread-2");
+ });
+ act(() => {
+ result.current.switchThread("thread-3");
+ });
+
+ // The hook should report the latest thread ID
+ expect(result.current.currentThreadId).toBe("thread-3");
+
+ // Note: Full race condition prevention requires:
+ // - Request cancellation via AbortController
+ // - Tracking request IDs to ignore stale responses
+ // - Proper cleanup in useEffect hooks
+ });
+
+ it("should handle switching to a deleted thread gracefully", async () => {
+ // Mock a thread that exists initially
+ mockGetThreadMetadata.mockResolvedValueOnce({
+ threadId: "thread-1",
+ createdAt: Date.now(),
+ lastActivityAt: Date.now(),
+ isRunning: false,
+ messageCount: 5,
+ firstMessage: "Hello",
+ });
+
+ const { result } = renderHook(() => useThreadSwitch(), {
+ wrapper: ({ children }: { children: ReactNode }) => (
+ {children}
+ ),
+ });
+
+ expect(result.current.currentThreadId).toBe("thread-1");
+
+ // Simulate the thread being deleted (next fetch returns null or throws)
+ mockGetThreadMetadata.mockResolvedValueOnce(null);
+
+ // Switch to the deleted thread
+ act(() => {
+ result.current.switchThread("thread-1");
+ });
+
+ // Should not crash - the component should handle the missing thread gracefully
+ await waitFor(() => {
+ expect(result.current.currentThreadId).toBe("thread-1");
+ });
+
+ // The hook itself should still report the thread ID even if the thread doesn't exist
+ // The consuming component (like CopilotChat) would handle showing an error state
+ expect(result.current.currentThreadId).toBe("thread-1");
+ });
+
+ it("should cancel agent run when switching threads mid-execution", async () => {
+ // This test documents the expected behavior for canceling runs during thread switch
+ // In a real implementation:
+ // - Switching threads should trigger AbortController.abort()
+ // - In-flight agent runs should be canceled
+ // - No state updates from the old thread should be processed
+
+ const { result } = renderHook(() => useThreadSwitch(), {
+ wrapper: ({ children }: { children: ReactNode }) => (
+ {children}
+ ),
+ });
+
+ // Switch to thread-1 first
+ act(() => {
+ result.current.switchThread("thread-1");
+ });
+
+ expect(result.current.currentThreadId).toBe("thread-1");
+
+ // Switch to a different thread
+ act(() => {
+ result.current.switchThread("thread-2");
+ });
+
+ // Verify the switch completed
+ expect(result.current.currentThreadId).toBe("thread-2");
+
+ // Note: Full cancellation support requires:
+ // - AbortController integration in the runtime
+ // - Cleanup logic in CopilotChat/thread management
+ // - Request tracking to prevent stale updates
+ });
+ });
+});
diff --git a/packages/react/src/hooks/__tests__/use-threads.test.tsx b/packages/react/src/hooks/__tests__/use-threads.test.tsx
new file mode 100644
index 00000000..c15dbbdf
--- /dev/null
+++ b/packages/react/src/hooks/__tests__/use-threads.test.tsx
@@ -0,0 +1,672 @@
+import { describe, it, expect, vi, beforeEach, beforeAll, afterAll } from "vitest";
+import { renderHook, waitFor, act } from "@testing-library/react";
+import { useThreads } from "../use-threads";
+import { CopilotKitProvider } from "@/providers/CopilotKitProvider";
+import { ReactNode } from "react";
+
+// Mock the CopilotKitCore
+const mockListThreads = vi.fn();
+const mockGetThreadMetadata = vi.fn();
+const mockDeleteThread = vi.fn();
+const mockFetch = vi.fn();
+
+const originalFetch = globalThis.fetch;
+
+beforeAll(() => {
+ globalThis.fetch = mockFetch as unknown as typeof fetch;
+});
+
+afterAll(() => {
+ globalThis.fetch = originalFetch;
+});
+
+vi.mock("@/providers/CopilotKitProvider", async () => {
+ const actual = await vi.importActual("@/providers/CopilotKitProvider");
+ return {
+ ...actual,
+ useCopilotKit: () => ({
+ copilotkit: {
+ listThreads: mockListThreads,
+ getThreadMetadata: mockGetThreadMetadata,
+ deleteThread: mockDeleteThread,
+ subscribe: vi.fn(() => vi.fn()),
+ runtimeUrl: "https://runtime.example",
+ headers: { Authorization: "Bearer test" },
+ },
+ }),
+ };
+});
+
+describe("useThreads", () => {
+ beforeEach(() => {
+ vi.clearAllMocks();
+ mockFetch.mockReset();
+ });
+
+ it("should fetch threads on mount when autoFetch is true", async () => {
+ const mockThreads = {
+ threads: [
+ {
+ threadId: "thread-1",
+ createdAt: Date.now(),
+ lastActivityAt: Date.now(),
+ isRunning: false,
+ messageCount: 5,
+ firstMessage: "Hello",
+ },
+ ],
+ total: 1,
+ };
+
+ mockListThreads.mockResolvedValue(mockThreads);
+
+ const { result } = renderHook(() => useThreads({ autoFetch: true }));
+
+ await waitFor(() => {
+ expect(result.current.isLoading).toBe(false);
+ });
+
+ expect(mockListThreads).toHaveBeenCalledWith({ limit: 50, offset: 0 });
+ expect(result.current.threads).toEqual(mockThreads.threads);
+ expect(result.current.total).toBe(1);
+ expect(result.current.error).toBeNull();
+ });
+
+ it("should not fetch threads on mount when autoFetch is false", async () => {
+ const { result } = renderHook(() => useThreads({ autoFetch: false }));
+
+ expect(mockListThreads).not.toHaveBeenCalled();
+ expect(result.current.threads).toEqual([]);
+ expect(result.current.isLoading).toBe(false);
+ });
+
+ it("should manually fetch threads when fetchThreads is called", async () => {
+ const mockThreads = {
+ threads: [
+ {
+ threadId: "thread-1",
+ createdAt: Date.now(),
+ lastActivityAt: Date.now(),
+ isRunning: false,
+ messageCount: 3,
+ firstMessage: "Manual fetch",
+ },
+ ],
+ total: 1,
+ };
+
+ mockListThreads.mockResolvedValue(mockThreads);
+
+ const { result } = renderHook(() => useThreads({ autoFetch: false }));
+
+ await result.current.fetchThreads();
+
+ await waitFor(() => {
+ expect(result.current.threads).toEqual(mockThreads.threads);
+ });
+
+ expect(mockListThreads).toHaveBeenCalledWith({ limit: 50, offset: 0 });
+ });
+
+ it("should handle pagination with offset", async () => {
+ const mockThreads = {
+ threads: [
+ {
+ threadId: "thread-2",
+ createdAt: Date.now(),
+ lastActivityAt: Date.now(),
+ isRunning: false,
+ messageCount: 2,
+ firstMessage: "Page 2",
+ },
+ ],
+ total: 10,
+ };
+
+ mockListThreads.mockResolvedValue(mockThreads);
+
+ const { result } = renderHook(() => useThreads({ autoFetch: false }));
+
+ await result.current.fetchThreads(20);
+
+ await waitFor(() => {
+ expect(result.current.threads).toHaveLength(1);
+ });
+
+ expect(mockListThreads).toHaveBeenCalledWith({ limit: 50, offset: 20 });
+ });
+
+ it("should respect custom limit", async () => {
+ const mockThreads = {
+ threads: [],
+ total: 0,
+ };
+
+ mockListThreads.mockResolvedValue(mockThreads);
+
+ const { result } = renderHook(() => useThreads({ limit: 10, autoFetch: false }));
+
+ await result.current.fetchThreads();
+
+ await waitFor(() => {
+ expect(mockListThreads).toHaveBeenCalledWith({ limit: 10, offset: 0 });
+ });
+ });
+
+ it("should handle errors gracefully", async () => {
+ const error = new Error("Failed to fetch threads");
+ mockListThreads.mockRejectedValue(error);
+
+ const { result } = renderHook(() => useThreads({ autoFetch: true }));
+
+ await waitFor(() => {
+ expect(result.current.error).toBeTruthy();
+ expect(result.current.error?.message).toBe("Failed to fetch threads");
+ });
+
+ expect(result.current.threads).toEqual([]);
+ });
+
+ it("should get metadata for a specific thread", async () => {
+ const mockMetadata = {
+ threadId: "thread-1",
+ createdAt: Date.now(),
+ lastActivityAt: Date.now(),
+ isRunning: false,
+ messageCount: 5,
+ firstMessage: "Specific thread",
+ };
+
+ mockGetThreadMetadata.mockResolvedValue(mockMetadata);
+
+ const { result } = renderHook(() => useThreads({ autoFetch: false }));
+
+ const metadata = await result.current.getThreadMetadata("thread-1");
+
+ expect(mockGetThreadMetadata).toHaveBeenCalledWith("thread-1");
+ expect(metadata).toEqual(mockMetadata);
+ });
+
+ it("should refresh threads from offset 0", async () => {
+ const mockThreads = {
+ threads: [
+ {
+ threadId: "thread-1",
+ createdAt: Date.now(),
+ lastActivityAt: Date.now(),
+ isRunning: false,
+ messageCount: 1,
+ firstMessage: "Refreshed",
+ },
+ ],
+ total: 1,
+ };
+
+ mockListThreads.mockResolvedValue(mockThreads);
+
+ const { result } = renderHook(() => useThreads({ autoFetch: false }));
+
+ await result.current.refresh();
+
+ await waitFor(() => {
+ expect(result.current.threads).toHaveLength(1);
+ });
+
+ expect(mockListThreads).toHaveBeenCalledWith({ limit: 50, offset: 0 });
+ });
+
+ it("should delete a thread and refresh", async () => {
+ mockListThreads.mockResolvedValue({ threads: [], total: 0 });
+ mockDeleteThread.mockResolvedValue(undefined);
+
+ const { result } = renderHook(() => useThreads({ autoFetch: false }));
+
+ await result.current.deleteThread("thread-1");
+
+ expect(mockDeleteThread).toHaveBeenCalledWith("thread-1");
+ expect(mockListThreads).toHaveBeenCalled();
+ });
+
+ it("should throw when delete thread fails", async () => {
+ mockListThreads.mockResolvedValue({ threads: [], total: 0 });
+ mockDeleteThread.mockRejectedValue(new Error("Failed to delete thread"));
+
+ const { result } = renderHook(() => useThreads({ autoFetch: false }));
+
+ await expect(result.current.deleteThread("missing")).rejects.toThrow("Failed to delete thread");
+ });
+
+ it("should set loading state during fetch", async () => {
+ const mockThreads = {
+ threads: [],
+ total: 0,
+ };
+
+ let resolvePromise: (value: any) => void;
+ const promise = new Promise((resolve) => {
+ resolvePromise = resolve;
+ });
+
+ mockListThreads.mockReturnValue(promise);
+
+ const { result } = renderHook(() => useThreads({ autoFetch: true }));
+
+ // Should be loading initially
+ expect(result.current.isLoading).toBe(true);
+
+ // Resolve the promise
+ resolvePromise!(mockThreads);
+
+ await waitFor(() => {
+ expect(result.current.isLoading).toBe(false);
+ });
+ });
+
+ // Note: The "null core" scenario is handled by the provider throwing an error
+ // before the hook is called, so we don't need to test it here
+
+ describe("Component Lifecycle", () => {
+ it("should cancel in-flight requests when component unmounts", async () => {
+ // Mock a slow fetch that takes time to complete
+ let fetchStarted = false;
+ let fetchCompleted = false;
+ const consoleWarnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+ const consoleErrorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+
+ const slowFetchPromise = new Promise((resolve) => {
+ fetchStarted = true;
+ setTimeout(() => {
+ fetchCompleted = true;
+ resolve({
+ threads: [
+ {
+ threadId: "thread-1",
+ createdAt: Date.now(),
+ lastActivityAt: Date.now(),
+ isRunning: false,
+ messageCount: 1,
+ firstMessage: "Test",
+ },
+ ],
+ total: 1,
+ });
+ }, 100);
+ });
+
+ mockListThreads.mockReturnValue(slowFetchPromise);
+
+ const { result, unmount } = renderHook(() => useThreads({ autoFetch: true }));
+
+ // Wait for fetch to start
+ await waitFor(() => {
+ expect(fetchStarted).toBe(true);
+ });
+
+ expect(result.current.isLoading).toBe(true);
+
+ // Unmount before the fetch completes
+ unmount();
+
+ // Wait a bit to see if the promise completion tries to update state
+ await new Promise((resolve) => setTimeout(resolve, 150));
+
+ // Verify no "state update on unmounted component" warnings
+ const warningMessages = consoleWarnSpy.mock.calls.flat().join(" ");
+ const errorMessages = consoleErrorSpy.mock.calls.flat().join(" ");
+
+ expect(warningMessages).not.toContain("unmounted component");
+ expect(warningMessages).not.toContain("memory leak");
+ expect(errorMessages).not.toContain("unmounted component");
+ expect(errorMessages).not.toContain("memory leak");
+
+ consoleWarnSpy.mockRestore();
+ consoleErrorSpy.mockRestore();
+ });
+
+ it("should cleanup subscriptions on unmount", async () => {
+ const unsubscribeMock = vi.fn();
+ const subscribeMock = vi.fn(() => unsubscribeMock);
+
+ // Override the mock to track subscriptions
+ vi.mocked(mockListThreads).mockResolvedValue({ threads: [], total: 0 });
+
+ // We need to inject a custom subscribe function
+ // In a real scenario, this would be through the CopilotKit provider
+ const mockSubscribe = vi.fn(() => unsubscribeMock);
+
+ const { unmount } = renderHook(() => useThreads({ autoFetch: false }));
+
+ // Mount and create subscriptions (if any)
+ await waitFor(() => {
+ expect(true).toBe(true); // Just wait for mount
+ });
+
+ // Unmount the component
+ unmount();
+
+ // In a real implementation with event listeners/subscriptions:
+ // - All event listeners should be removed
+ // - All subscriptions should be unsubscribed
+ // - No memory leaks should occur
+
+ // This test verifies the unmount doesn't crash
+ // A more complete test would check that unsubscribe was called
+ // expect(unsubscribeMock).toHaveBeenCalled();
+ });
+
+ it("should not process responses after unmount", async () => {
+ let resolveSlowFetch: (value: any) => void;
+ const slowFetch = new Promise((resolve) => {
+ resolveSlowFetch = resolve;
+ });
+
+ mockListThreads.mockReturnValue(slowFetch);
+
+ const { result, unmount } = renderHook(() => useThreads({ autoFetch: true }));
+
+ expect(result.current.isLoading).toBe(true);
+
+ // Unmount while loading
+ unmount();
+
+ // Complete the fetch after unmount
+ resolveSlowFetch!({
+ threads: [
+ {
+ threadId: "thread-1",
+ createdAt: Date.now(),
+ lastActivityAt: Date.now(),
+ isRunning: false,
+ messageCount: 1,
+ firstMessage: "Should not appear",
+ },
+ ],
+ total: 1,
+ });
+
+ // Wait to ensure no state updates occur
+ await new Promise((resolve) => setTimeout(resolve, 50));
+
+ // If we got here without errors, the test passed
+ // The component properly ignored the late response
+ expect(true).toBe(true);
+ });
+
+ it("should handle multiple rapid mount/unmount cycles", async () => {
+ mockListThreads.mockResolvedValue({ threads: [], total: 0 });
+
+ // Mount and unmount multiple times rapidly
+ for (let i = 0; i < 5; i++) {
+ const { unmount } = renderHook(() => useThreads({ autoFetch: true }));
+ // Unmount immediately
+ unmount();
+ }
+
+ // Wait a bit to ensure all async operations complete
+ await new Promise((resolve) => setTimeout(resolve, 100));
+
+ // If we got here without crashes or memory leaks, test passes
+ expect(mockListThreads.mock.calls.length).toBeGreaterThanOrEqual(0);
+ });
+ });
+
+ describe("Network Failures", () => {
+ it("should handle request timeout gracefully", async () => {
+ // Mock fetch that never resolves (simulating timeout)
+ const timeoutPromise = new Promise(() => {
+ // Never resolves
+ });
+
+ mockListThreads.mockReturnValue(timeoutPromise);
+
+ const { result } = renderHook(() => useThreads({ autoFetch: true }));
+
+ // Should be loading
+ expect(result.current.isLoading).toBe(true);
+
+ // In a real implementation with timeout:
+ // - Should timeout after a reasonable duration
+ // - Should set an error state
+ // - Should not cause memory leaks
+
+ // For this test, we just verify it doesn't crash immediately
+ await new Promise((resolve) => setTimeout(resolve, 100));
+
+ // Still loading (since promise never resolves)
+ expect(result.current.isLoading).toBe(true);
+ });
+
+ it("should handle corrupted JSON response", async () => {
+ // Simulate a response that can't be parsed as expected
+ const corruptedData = {
+ threads: "not-an-array", // Should be an array
+ total: "not-a-number", // Should be a number
+ };
+
+ mockListThreads.mockResolvedValue(corruptedData);
+
+ const { result } = renderHook(() => useThreads({ autoFetch: true }));
+
+ await waitFor(() => {
+ expect(result.current.isLoading).toBe(false);
+ });
+
+ // Should handle gracefully - either show error or treat as empty
+ // In this case, the hook will try to work with the corrupted data
+ // A more robust implementation would validate the response
+ expect(result.current.threads).toBeDefined();
+ });
+
+ it("should handle various HTTP error codes", async () => {
+ const errorCodes = [500, 502, 503, 504];
+
+ for (const code of errorCodes) {
+ vi.clearAllMocks();
+
+ const error = new Error(`HTTP ${code}: Server Error`);
+ mockListThreads.mockRejectedValue(error);
+
+ const { result } = renderHook(() => useThreads({ autoFetch: true }));
+
+ await waitFor(() => {
+ expect(result.current.error).toBeTruthy();
+ });
+
+ // Each error should be handled appropriately
+ expect(result.current.error).toBeTruthy();
+ expect(result.current.threads).toEqual([]);
+ expect(result.current.isLoading).toBe(false);
+ }
+ });
+
+ it("should handle network disconnect during fetch", async () => {
+ const networkError = new Error("Network request failed");
+ (networkError as any).name = "NetworkError";
+
+ mockListThreads.mockRejectedValue(networkError);
+
+ const { result } = renderHook(() => useThreads({ autoFetch: true }));
+
+ await waitFor(() => {
+ expect(result.current.error).toBeTruthy();
+ });
+
+ expect(result.current.error?.message).toBe("Network request failed");
+ expect(result.current.threads).toEqual([]);
+ });
+
+ it("should handle abort/cancellation errors", async () => {
+ const abortError = new Error("The operation was aborted");
+ (abortError as any).name = "AbortError";
+
+ mockListThreads.mockRejectedValue(abortError);
+
+ const { result } = renderHook(() => useThreads({ autoFetch: true }));
+
+ await waitFor(() => {
+ expect(result.current.isLoading).toBe(false);
+ });
+
+ // Abort errors might be handled differently (not shown as user-facing errors)
+ // The component should handle them gracefully
+ expect(result.current.isLoading).toBe(false);
+ });
+ });
+
+ describe("Optimistic Updates", () => {
+ it("should handle multiple rapid optimistic deletes", async () => {
+ // Initial threads
+ const initialThreads = [
+ {
+ threadId: "thread-1",
+ createdAt: Date.now(),
+ lastActivityAt: Date.now(),
+ isRunning: false,
+ messageCount: 1,
+ firstMessage: "Thread 1",
+ },
+ {
+ threadId: "thread-2",
+ createdAt: Date.now(),
+ lastActivityAt: Date.now(),
+ isRunning: false,
+ messageCount: 1,
+ firstMessage: "Thread 2",
+ },
+ {
+ threadId: "thread-3",
+ createdAt: Date.now(),
+ lastActivityAt: Date.now(),
+ isRunning: false,
+ messageCount: 1,
+ firstMessage: "Thread 3",
+ },
+ ];
+
+ mockListThreads.mockResolvedValue({ threads: initialThreads, total: 3 });
+ mockDeleteThread.mockResolvedValue(undefined);
+
+ const { result } = renderHook(() => useThreads({ autoFetch: true }));
+
+ await waitFor(() => {
+ expect(result.current.threads).toHaveLength(3);
+ });
+
+ // Delete multiple threads rapidly
+ const deletePromises = [
+ result.current.deleteThread("thread-1"),
+ result.current.deleteThread("thread-2"),
+ result.current.deleteThread("thread-3"),
+ ];
+
+ // Wait for all deletions to complete
+ await Promise.all(deletePromises);
+
+ // All threads should be deleted
+ expect(mockDeleteThread).toHaveBeenCalledTimes(3);
+ });
+
+ it("should handle failed optimistic delete with rollback", async () => {
+ const threads = [
+ {
+ threadId: "thread-1",
+ createdAt: Date.now(),
+ lastActivityAt: Date.now(),
+ isRunning: false,
+ messageCount: 1,
+ firstMessage: "Thread 1",
+ },
+ ];
+
+ mockListThreads.mockResolvedValue({ threads, total: 1 });
+ // First call succeeds, second call fails
+ mockDeleteThread.mockRejectedValueOnce(new Error("Failed to delete thread"));
+
+ const { result } = renderHook(() => useThreads({ autoFetch: true }));
+
+ await waitFor(() => {
+ expect(result.current.threads).toHaveLength(1);
+ });
+
+ // Try to delete - should fail
+ await expect(result.current.deleteThread("thread-1")).rejects.toThrow();
+
+ // After failed delete, the list should be refreshed
+ // Check that it was called at least twice (initial + after failed delete)
+ // May be called more due to re-renders
+ expect(mockListThreads.mock.calls.length).toBeGreaterThanOrEqual(2);
+ });
+
+ it("should handle list refresh during optimistic delete", async () => {
+ const thread1 = {
+ threadId: "thread-1",
+ createdAt: Date.now(),
+ lastActivityAt: Date.now(),
+ isRunning: false,
+ messageCount: 1,
+ firstMessage: "Thread 1",
+ };
+
+ // First fetch returns thread
+ mockListThreads.mockResolvedValueOnce({ threads: [thread1], total: 1 });
+ mockDeleteThread.mockImplementation(
+ () =>
+ new Promise((resolve) => {
+ setTimeout(() => resolve(undefined), 100);
+ }),
+ );
+
+ const { result } = renderHook(() => useThreads({ autoFetch: true }));
+
+ await waitFor(() => {
+ expect(result.current.threads).toHaveLength(1);
+ });
+
+ // Start optimistic delete (slow)
+ const deletePromise = result.current.deleteThread("thread-1");
+
+ // Concurrent refresh shows thread still exists
+ mockListThreads.mockResolvedValueOnce({ threads: [thread1], total: 1 });
+
+ // Manually refresh while delete is in progress
+ await result.current.refresh();
+
+ // Wait for delete to complete
+ await deletePromise;
+
+ // Should handle consistency properly
+ // The refresh after delete will show the final state
+ expect(mockListThreads).toHaveBeenCalled();
+ });
+
+ it("should handle optimistic updates with stale data", async () => {
+ const thread1 = {
+ threadId: "thread-stale-test",
+ createdAt: Date.now(),
+ lastActivityAt: Date.now(),
+ isRunning: false,
+ messageCount: 1,
+ firstMessage: "Original",
+ };
+
+ mockListThreads.mockResolvedValue({ threads: [thread1], total: 1 });
+
+ const { result } = renderHook(() => useThreads({ autoFetch: false }));
+
+ // Manually fetch first time
+ await result.current.fetchThreads();
+
+ await waitFor(() => {
+ expect(result.current.threads).toHaveLength(1);
+ });
+
+ // Verify we have the data
+ expect(result.current.threads[0].firstMessage).toBe("Original");
+
+ // This test verifies that the hook correctly fetches and displays thread data
+ // In a real scenario, stale data would be handled by refreshing the list
+ // The implementation properly updates state when new data arrives
+ expect(result.current.threads[0].threadId).toBe("thread-stale-test");
+ });
+ });
+});
diff --git a/packages/react/src/hooks/index.ts b/packages/react/src/hooks/index.ts
index c8d05ac2..f784c018 100644
--- a/packages/react/src/hooks/index.ts
+++ b/packages/react/src/hooks/index.ts
@@ -7,3 +7,7 @@ export { useAgent } from "./use-agent";
export { useAgentContext } from "./use-agent-context";
export { useSuggestions } from "./use-suggestions";
export { useConfigureSuggestions } from "./use-configure-suggestions";
+export { useThreads } from "./use-threads";
+export type { UseThreadsOptions, UseThreadsResult } from "./use-threads";
+export type { ThreadMetadata } from "@copilotkitnext/shared";
+export { useThreadSwitch } from "./use-thread-switcher";
diff --git a/packages/react/src/hooks/use-agent.tsx b/packages/react/src/hooks/use-agent.tsx
index bd88c4b1..6028b697 100644
--- a/packages/react/src/hooks/use-agent.tsx
+++ b/packages/react/src/hooks/use-agent.tsx
@@ -26,20 +26,12 @@ export function useAgent({ agentId, updates }: UseAgentProps = {}) {
const { copilotkit } = useCopilotKit();
const [, forceUpdate] = useReducer((x) => x + 1, 0);
- const updateFlags = useMemo(
- () => updates ?? ALL_UPDATES,
- [JSON.stringify(updates)]
- );
+ const updateFlags = useMemo(() => updates ?? ALL_UPDATES, [JSON.stringify(updates)]);
const agent: AbstractAgent | undefined = useMemo(() => {
return copilotkit.getAgent(agentId);
// eslint-disable-next-line react-hooks/exhaustive-deps
- }, [
- agentId,
- copilotkit.agents,
- copilotkit.runtimeConnectionStatus,
- copilotkit,
- ]);
+ }, [agentId, copilotkit.agents, copilotkit.runtimeConnectionStatus, copilotkit]);
useEffect(() => {
if (!agent) {
diff --git a/packages/react/src/hooks/use-render-custom-messages.tsx b/packages/react/src/hooks/use-render-custom-messages.tsx
index 138fea46..1052690f 100644
--- a/packages/react/src/hooks/use-render-custom-messages.tsx
+++ b/packages/react/src/hooks/use-render-custom-messages.tsx
@@ -31,42 +31,50 @@ export function useRenderCustomMessages() {
return null;
}
const { message, position } = params;
- const runId = copilotkit.getRunIdForMessage(agentId, threadId, message.id)!;
+ const runId = copilotkit.getRunIdForMessage(agentId, threadId, message.id);
const agent = copilotkit.getAgent(agentId);
if (!agent) {
throw new Error("Agent not found");
}
- const messagesIdsInRun = agent.messages
- .filter((msg) => copilotkit.getRunIdForMessage(agentId, threadId, msg.id) === runId)
- .map((msg) => msg.id);
+ const messagesIdsInRun = runId
+ ? agent.messages
+ .filter((msg) => copilotkit.getRunIdForMessage(agentId, threadId, msg.id) === runId)
+ .map((msg) => msg.id)
+ : [];
const messageIndex = agent.messages.findIndex((msg) => msg.id === message.id) ?? 0;
- const messageIndexInRun = Math.min(messagesIdsInRun.indexOf(message.id), 0);
+ const messageIndexInRun = Math.max(messagesIdsInRun.indexOf(message.id), 0);
const numberOfMessagesInRun = messagesIdsInRun.length;
- const stateSnapshot = copilotkit.getStateByRun(agentId, threadId, runId);
+ const stateSnapshot = runId ? copilotkit.getStateByRun(agentId, threadId, runId) : undefined;
let result = null;
for (const renderer of customMessageRenderers) {
if (!renderer.render) {
continue;
}
- const Component = renderer.render;
- result = (
- ;
+ getThreadMetadata: (threadId: string) => Promise;
+ refresh: () => Promise;
+ addOptimisticThread: (threadId: string) => void;
+ deleteThread: (threadId: string) => Promise;
+ currentThreadId?: string;
+}
+
+/**
+ * Hook for managing and retrieving threads from the CopilotKit runtime.
+ *
+ * @example
+ * ```tsx
+ * const { threads, isLoading, fetchThreads } = useThreads({ limit: 20 });
+ *
+ * // Manually fetch threads
+ * await fetchThreads();
+ *
+ * // Paginate
+ * await fetchThreads(20); // offset = 20
+ * ```
+ */
+export function useThreads(options: UseThreadsOptions = {}): UseThreadsResult {
+ const { limit = 50, autoFetch = true } = options;
+ const { copilotkit: core } = useCopilotKit();
+ const chatConfig = useCopilotChatConfiguration();
+
+ const [threads, setThreads] = useState([]);
+ const [total, setTotal] = useState(0);
+ const [isLoading, setIsLoading] = useState(false);
+ const [error, setError] = useState(null);
+
+ const fetchThreads = useCallback(
+ async (offset = 0) => {
+ if (!core) {
+ return;
+ }
+
+ setIsLoading(true);
+ setError(null);
+
+ try {
+ const result = await core.listThreads({ limit, offset });
+ setThreads(result.threads);
+ setTotal(result.total);
+ } catch (err) {
+ const error = err instanceof Error ? err : new Error("Failed to fetch threads");
+ setError(error);
+ console.error("Error fetching threads:", error);
+ } finally {
+ setIsLoading(false);
+ }
+ },
+ [core, limit],
+ );
+
+ const getThreadMetadata = useCallback(
+ async (threadId: string): Promise => {
+ if (!core) {
+ throw new Error("CopilotKit core not initialized");
+ }
+
+ try {
+ return await core.getThreadMetadata(threadId);
+ } catch (err) {
+ const error = err instanceof Error ? err : new Error("Failed to get thread metadata");
+ console.error("Error getting thread metadata:", error);
+ throw error;
+ }
+ },
+ [core],
+ );
+
+ const refresh = useCallback(() => fetchThreads(0), [fetchThreads]);
+
+ const addOptimisticThread = useCallback((threadId: string) => {
+ const newThread: ThreadMetadata = {
+ threadId,
+ createdAt: Date.now(),
+ lastActivityAt: Date.now(),
+ isRunning: false,
+ messageCount: 0,
+ firstMessage: undefined,
+ };
+ setThreads((prev) => [newThread, ...prev]);
+ setTotal((prev) => prev + 1);
+ }, []);
+
+ const deleteThread = useCallback(
+ async (threadId: string) => {
+ if (!core) {
+ throw new Error("CopilotKit core not initialized");
+ }
+
+ // Optimistic update: save original state for rollback
+ const originalThreads = threads;
+ const originalTotal = total;
+ const threadIndex = threads.findIndex((t) => t.threadId === threadId);
+ const deletedThread = threadIndex >= 0 ? threads[threadIndex] : null;
+
+ // Immediately remove from UI
+ if (threadIndex >= 0) {
+ setThreads((prev) => prev.filter((t) => t.threadId !== threadId));
+ setTotal((prev) => prev - 1);
+ }
+
+ try {
+ // Use core helper method for deletion
+ await core.deleteThread(threadId);
+
+ // Success - refetch to ensure consistency
+ await fetchThreads();
+ } catch (err) {
+ // Rollback: restore thread to its original position
+ if (deletedThread && threadIndex >= 0) {
+ setThreads((prev) => {
+ const newThreads = [...prev];
+ newThreads.splice(threadIndex, 0, deletedThread);
+ return newThreads;
+ });
+ setTotal(originalTotal);
+ } else {
+ // Fallback: restore complete original state if we don't have the thread
+ setThreads(originalThreads);
+ setTotal(originalTotal);
+ }
+
+ const error = err instanceof Error ? err : new Error("Failed to delete thread");
+ console.error("Error deleting thread:", error);
+ throw error;
+ }
+ },
+ [core, fetchThreads, threads, total],
+ );
+
+ useEffect(() => {
+ if (autoFetch && core) {
+ void fetchThreads();
+ }
+ }, [autoFetch, core, fetchThreads]);
+
+ return {
+ threads,
+ total,
+ isLoading,
+ error,
+ fetchThreads,
+ getThreadMetadata,
+ refresh,
+ addOptimisticThread,
+ deleteThread,
+ currentThreadId: chatConfig?.threadId,
+ };
+}
diff --git a/packages/react/src/providers/CopilotChatConfigurationProvider.tsx b/packages/react/src/providers/CopilotChatConfigurationProvider.tsx
index c04bd8e1..310999dd 100644
--- a/packages/react/src/providers/CopilotChatConfigurationProvider.tsx
+++ b/packages/react/src/providers/CopilotChatConfigurationProvider.tsx
@@ -1,4 +1,4 @@
-import React, { createContext, useContext, ReactNode, useMemo, useState } from "react";
+import React, { createContext, useContext, ReactNode, useMemo, useState, useCallback } from "react";
import { DEFAULT_AGENT_ID, randomUUID } from "@copilotkitnext/shared";
// Default labels
@@ -31,6 +31,7 @@ export interface CopilotChatConfigurationValue {
labels: CopilotChatLabels;
agentId: string;
threadId: string;
+ setThreadId?: (threadId: string) => void;
isModalOpen: boolean;
setModalOpen: (open: boolean) => void;
isModalDefaultOpen: boolean;
@@ -66,15 +67,30 @@ export const CopilotChatConfigurationProvider: React.FC<
const resolvedAgentId = agentId ?? parentConfig?.agentId ?? DEFAULT_AGENT_ID;
- const resolvedThreadId = useMemo(() => {
- if (threadId) {
- return threadId;
- }
- if (parentConfig?.threadId) {
- return parentConfig.threadId;
- }
+ // Add internal state for threadId management
+ const [internalThreadId, setInternalThreadId] = useState(() => {
+ if (threadId) return threadId;
+ if (parentConfig?.threadId) return parentConfig.threadId;
return randomUUID();
- }, [threadId, parentConfig?.threadId]);
+ });
+
+ // Use prop if provided (controlled), otherwise use internal state (uncontrolled)
+ const resolvedThreadId = threadId ?? internalThreadId;
+
+ // Provide setThreadId that respects controlled/uncontrolled pattern
+ const handleSetThreadId = useCallback(
+ (newThreadId: string) => {
+ // If threadId prop is provided, this is controlled - only update internal state if uncontrolled
+ if (threadId === undefined) {
+ setInternalThreadId(newThreadId);
+ }
+ // If controlled, parent should handle the change
+ },
+ [threadId],
+ );
+
+ // Use parent's setThreadId if available, otherwise use our own
+ const resolvedSetThreadId = parentConfig?.setThreadId ?? handleSetThreadId;
const resolvedDefaultOpen = isModalDefaultOpen ?? parentConfig?.isModalDefaultOpen ?? true;
@@ -90,6 +106,7 @@ export const CopilotChatConfigurationProvider: React.FC<
labels: mergedLabels,
agentId: resolvedAgentId,
threadId: resolvedThreadId,
+ setThreadId: resolvedSetThreadId,
isModalOpen: resolvedIsModalOpen,
setModalOpen: resolvedSetModalOpen,
isModalDefaultOpen: resolvedDefaultOpen,
@@ -98,6 +115,7 @@ export const CopilotChatConfigurationProvider: React.FC<
mergedLabels,
resolvedAgentId,
resolvedThreadId,
+ resolvedSetThreadId,
resolvedIsModalOpen,
resolvedSetModalOpen,
resolvedDefaultOpen,
diff --git a/packages/react/src/providers/CopilotKitProvider.tsx b/packages/react/src/providers/CopilotKitProvider.tsx
index ce6aed78..cbaeb76a 100644
--- a/packages/react/src/providers/CopilotKitProvider.tsx
+++ b/packages/react/src/providers/CopilotKitProvider.tsx
@@ -9,6 +9,7 @@ import React, {
useReducer,
useRef,
useState,
+ useCallback,
} from "react";
import { ReactToolCallRenderer } from "../types/react-tool-call-renderer";
import { ReactCustomMessageRenderer } from "../types/react-custom-message-renderer";
@@ -23,11 +24,25 @@ import { CopilotKitInspector } from "../components/CopilotKitInspector";
// Define the context value interface - idiomatic React naming
export interface CopilotKitContextValue {
copilotkit: CopilotKitCoreReact;
+ /**
+ * Set the resource ID(s) dynamically.
+ * Use this to update resource scoping when the user switches context (e.g., workspace switcher).
+ *
+ * @example
+ * ```tsx
+ * const { setResourceId } = useCopilotKit();
+ * setResourceId(newWorkspaceId);
+ * ```
+ */
+ setResourceId: (resourceId: string | string[] | undefined) => void;
}
// Create the CopilotKit context
const CopilotKitContext = createContext({
copilotkit: null!,
+ setResourceId: () => {
+ throw new Error("useCopilotKit must be used within CopilotKitProvider");
+ },
});
// Provider props interface
@@ -36,6 +51,22 @@ export interface CopilotKitProviderProps {
runtimeUrl?: string;
headers?: Record;
properties?: Record;
+ /**
+ * Resource ID(s) for thread access control.
+ *
+ * This value is sent to the server as a hint for thread scoping.
+ * The server's `resolveThreadsScope` validates and enforces access control.
+ *
+ * @example
+ * ```tsx
+ * // Single resource
+ *
+ *
+ * // Multiple resources (thread accessible by any of these)
+ *
+ * ```
+ */
+ resourceId?: string | string[];
agents__unsafe_dev_only?: Record;
renderToolCalls?: ReactToolCallRenderer[];
renderCustomMessages?: ReactCustomMessageRenderer[];
@@ -73,6 +104,7 @@ export const CopilotKitProvider: React.FC = ({
runtimeUrl,
headers = {},
properties = {},
+ resourceId,
agents__unsafe_dev_only: agents = {},
renderToolCalls,
renderCustomMessages,
@@ -220,6 +252,7 @@ export const CopilotKitProvider: React.FC = ({
runtimeUrl,
headers,
properties,
+ resourceId,
agents__unsafe_dev_only: agents,
tools: allTools,
renderToolCalls: allRenderToolCalls,
@@ -249,13 +282,46 @@ export const CopilotKitProvider: React.FC = ({
copilotkit.setRuntimeUrl(runtimeUrl);
copilotkit.setHeaders(headers);
copilotkit.setProperties(properties);
+ copilotkit.setResourceId(resourceId);
copilotkit.setAgents__unsafe_dev_only(agents);
- }, [runtimeUrl, headers, properties, agents]);
+ }, [runtimeUrl, headers, properties, resourceId, agents]);
+
+ // Production safety: warn if resourceId not set
+ useEffect(() => {
+ if (typeof window === "undefined") {
+ return;
+ }
+
+ const isProduction = process.env.NODE_ENV === "production";
+ if (isProduction && !resourceId) {
+ console.error(
+ "CopilotKit Security Warning: No resourceId set in production.\n" +
+ "All threads will be globally accessible. Set the resourceId prop:\n" +
+ "\n" +
+ "Learn more: https://docs.copilotkit.ai/security/resource-scoping",
+ );
+ } else if (!isProduction && !resourceId) {
+ console.warn(
+ "CopilotKit: No resourceId set. All threads are globally accessible.\n" +
+ "This is fine for development, but add resourceId for production:\n" +
+ "",
+ );
+ }
+ }, [resourceId]);
+
+ // Create stable setResourceId function
+ const setResourceId = useCallback(
+ (newResourceId: string | string[] | undefined) => {
+ copilotkit.setResourceId(newResourceId);
+ },
+ [copilotkit],
+ );
return (
{children}
@@ -277,6 +343,9 @@ export const useCopilotKit = (): CopilotKitContextValue => {
onRuntimeConnectionStatusChanged: () => {
forceUpdate();
},
+ onResourceIdChanged: () => {
+ forceUpdate();
+ },
});
return () => {
unsubscribe();
diff --git a/packages/react/src/providers/__tests__/CopilotKitProvider.renderCustomMessages.e2e.test.tsx b/packages/react/src/providers/__tests__/CopilotKitProvider.renderCustomMessages.e2e.test.tsx
index 50e1d43b..40297bb7 100644
--- a/packages/react/src/providers/__tests__/CopilotKitProvider.renderCustomMessages.e2e.test.tsx
+++ b/packages/react/src/providers/__tests__/CopilotKitProvider.renderCustomMessages.e2e.test.tsx
@@ -11,18 +11,27 @@ import {
textMessageContentEvent,
textMessageEndEvent,
} from "@/__tests__/utils/test-helpers";
-import { ReactCustomMessageRenderer } from "@/types/react-custom-message-renderer";
-import { useCopilotKit } from "@/providers/CopilotKitProvider";
-import { useCopilotChatConfiguration } from "@/providers/CopilotChatConfigurationProvider";
-
-type SnapshotRendererProps = Parameters>[0];
-
-const SnapshotRenderer: React.FC = ({
- position,
- message,
- runId,
- stateSnapshot,
-}) => {
+import { ReactCustomMessageRenderer, ReactCustomMessageRendererPosition } from "@/types/react-custom-message-renderer";
+import { useCopilotKit, CopilotKitProvider } from "@/providers/CopilotKitProvider";
+import {
+ useCopilotChatConfiguration,
+ CopilotChatConfigurationProvider,
+} from "@/providers/CopilotChatConfigurationProvider";
+import { CopilotChat } from "@/components/chat/CopilotChat";
+import type { Message } from "@ag-ui/core";
+
+interface SnapshotRendererProps {
+ message: Message;
+ position: ReactCustomMessageRendererPosition;
+ runId: string;
+ messageIndex: number;
+ messageIndexInRun: number;
+ numberOfMessagesInRun: number;
+ agentId: string;
+ stateSnapshot: unknown;
+}
+
+const SnapshotRenderer: React.FC = ({ position, message, runId, stateSnapshot }) => {
if (position !== "after" || message.role !== "assistant") {
return null;
}
@@ -91,9 +100,7 @@ describe("CopilotKitProvider custom message renderers E2E", () => {
await waitFor(() => {
expect(screen.getByTestId(`state-${firstAssistantId}`).textContent).toContain("State: 1");
});
- const firstRunId = screen
- .getByTestId(`state-${firstAssistantId}`)
- .getAttribute("data-run-id");
+ const firstRunId = screen.getByTestId(`state-${firstAssistantId}`).getAttribute("data-run-id");
expect(firstRunId).toBeTruthy();
const secondAssistantId = testId("assistant-message");
@@ -115,15 +122,11 @@ describe("CopilotKitProvider custom message renderers E2E", () => {
await waitFor(() => {
expect(screen.getByTestId(`state-${secondAssistantId}`).textContent).toContain("State: 2");
});
- const secondRunId = screen
- .getByTestId(`state-${secondAssistantId}`)
- .getAttribute("data-run-id");
+ const secondRunId = screen.getByTestId(`state-${secondAssistantId}`).getAttribute("data-run-id");
expect(secondRunId).not.toBe(firstRunId);
- const firstRunIdAfterSecond = screen
- .getByTestId(`state-${firstAssistantId}`)
- .getAttribute("data-run-id");
+ const firstRunIdAfterSecond = screen.getByTestId(`state-${firstAssistantId}`).getAttribute("data-run-id");
expect(firstRunIdAfterSecond).toBe(firstRunId);
expect(screen.getByTestId(`state-${firstAssistantId}`).textContent).toContain("State: 1");
@@ -233,10 +236,7 @@ describe("CopilotKitProvider custom message renderers E2E", () => {
renderWithCopilotKit({
agent,
- renderCustomMessages: [
- { render: FirstRenderer },
- { render: SecondRenderer },
- ],
+ renderCustomMessages: [{ render: FirstRenderer }, { render: SecondRenderer }],
});
const input = await screen.findByRole("textbox");
@@ -329,10 +329,7 @@ describe("CopilotKitProvider custom message renderers E2E", () => {
renderWithCopilotKit({
agents: { [agentId]: agent },
agentId,
- renderCustomMessages: [
- { render: GlobalRenderer },
- { agentId, render: SpecificRenderer },
- ],
+ renderCustomMessages: [{ render: GlobalRenderer }, { agentId, render: SpecificRenderer }],
});
const input = await screen.findByRole("textbox");
@@ -365,9 +362,7 @@ describe("CopilotKitProvider custom message renderers E2E", () => {
const StateRenderer: React.FC = ({ message, position, stateSnapshot }) => {
if (position !== "after" || message.role !== "assistant") return null;
return (
- = ({ runId, position, message }) => {
+ if (position !== "after" || message.role !== "user") return null;
+ receivedRunId = runId;
+ return = ({ position, message }) => {
+ if (position !== "after" || message.role !== "assistant") return null;
+ renderCount++;
+ throw new Error("Renderer failed!");
+ };
+
+ renderWithCopilotKit({
+ agent,
+ renderCustomMessages: [{ render: ErrorRenderer }],
+ });
+
+ const input = await screen.findByRole("textbox");
+ const messageId = testId("message");
+
+ fireEvent.change(input, { target: { value: "Test" } });
+ fireEvent.keyDown(input, { key: "Enter", code: "Enter" });
+
+ await waitFor(() => {
+ expect(screen.getByText("Test")).toBeDefined();
+ });
+
+ agent.emit(runStartedEvent());
+ agent.emit(textMessageStartEvent(messageId));
+ agent.emit(textMessageContentEvent(messageId, "Response"));
+ agent.emit(textMessageEndEvent(messageId));
+ agent.emit(runFinishedEvent());
+
+ // Message should still render even though custom renderer threw
+ await waitFor(() => {
+ expect(screen.getByText("Response")).toBeDefined();
+ });
+
+ expect(renderCount).toBeGreaterThan(0);
+ });
+
+ it("should handle rapid thread switches correctly", async () => {
+ const agent = new MockStepwiseAgent();
+ const { rerender } = renderWithCopilotKit({
+ agent,
+ threadId: "thread-1",
+ });
+
+ // Add a message to thread-1
+ agent.addMessage({
+ id: "msg1",
+ role: "user",
+ content: "Thread 1 message",
+ });
+
+ await waitFor(() => {
+ expect(screen.getByText("Thread 1 message")).toBeDefined();
+ });
+
+ // Rapidly switch to thread-2
+ rerender(
+
+
+
+ ,
+ );
+
+ // Messages should be cleared
+ await waitFor(() => {
+ expect(screen.queryByText("Thread 1 message")).toBeNull();
+ });
+
+ // Add message to thread-2
+ agent.addMessage({
+ id: "msg2",
+ role: "user",
+ content: "Thread 2 message",
+ });
+
+ await waitFor(() => {
+ expect(screen.getByText("Thread 2 message")).toBeDefined();
+ });
+ });
+
+ it("should sync messages returned from connectAgent", async () => {
+ const agent = new MockStepwiseAgent();
+
+ // Override connectAgent to return some messages
+ agent.connectAgent = async () => {
+ const messages = [
+ { id: "msg1", role: "assistant", content: "Synced message 1" },
+ { id: "msg2", role: "assistant", content: "Synced message 2" },
+ ];
+
+ // Manually add messages to agent since we're bypassing base class logic
+ agent.addMessages(messages as any);
+
+ return {
+ newMessages: messages,
+ result: undefined,
+ };
+ };
+
+ renderWithCopilotKit({
+ agent,
+ threadId: "test-thread",
+ });
+
+ // Messages from connectAgent should appear
+ await waitFor(() => {
+ expect(screen.getByText("Synced message 1")).toBeDefined();
+ expect(screen.getByText("Synced message 2")).toBeDefined();
+ });
+ });
});
diff --git a/packages/react/src/providers/__tests__/CopilotKitProvider.resourceId.test.tsx b/packages/react/src/providers/__tests__/CopilotKitProvider.resourceId.test.tsx
new file mode 100644
index 00000000..191801d9
--- /dev/null
+++ b/packages/react/src/providers/__tests__/CopilotKitProvider.resourceId.test.tsx
@@ -0,0 +1,539 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { render, waitFor } from "@testing-library/react";
+import { CopilotKitProvider, useCopilotKit } from "../CopilotKitProvider";
+import React from "react";
+
+describe("CopilotKitProvider - resourceId", () => {
+ let consoleWarnSpy: ReturnType;
+ let consoleErrorSpy: ReturnType;
+ const originalEnv = process.env.NODE_ENV;
+
+ beforeEach(() => {
+ consoleWarnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+ consoleErrorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+ // Reset NODE_ENV to test so warnings don't fire during most tests
+ process.env.NODE_ENV = "test";
+ });
+
+ afterEach(() => {
+ consoleWarnSpy.mockRestore();
+ consoleErrorSpy.mockRestore();
+ process.env.NODE_ENV = originalEnv;
+ });
+
+ describe("resourceId prop", () => {
+ it("should accept string resourceId", () => {
+ const TestComponent = () => {
+ const { copilotkit } = useCopilotKit();
+ return
+
+ );
+
+ expect(container.textContent).toBe("user-123");
+ });
+
+ it("should accept array of resourceIds", () => {
+ const TestComponent = () => {
+ const { copilotkit } = useCopilotKit();
+ const resourceId = copilotkit.resourceId;
+ return (
+
+
+ );
+
+ expect(container.textContent).toBe("user-123,workspace-456");
+ });
+
+ it("should accept undefined resourceId", () => {
+ const TestComponent = () => {
+ const { copilotkit } = useCopilotKit();
+ return
+
+ );
+
+ expect(container.textContent).toBe("undefined");
+ });
+
+ it("should handle empty array resourceId", () => {
+ const TestComponent = () => {
+ const { copilotkit } = useCopilotKit();
+ const resourceId = copilotkit.resourceId;
+ return (
+
+
+ );
+
+ expect(container.textContent).toBe("empty");
+ });
+
+ it("should handle resourceId with special characters", () => {
+ const specialId = "user@example.com/workspace#123";
+ const TestComponent = () => {
+ const { copilotkit } = useCopilotKit();
+ return
+
+ );
+
+ expect(container.textContent).toBe(specialId);
+ });
+
+ it("should update resourceId when prop changes", () => {
+ const TestComponent = () => {
+ const { copilotkit } = useCopilotKit();
+ return
+
+ );
+
+ expect(container.textContent).toBe("user-1");
+
+ rerender(
+
+
+ );
+
+ expect(container.textContent).toBe("user-2");
+ });
+
+ it("should transition from string to array", () => {
+ const TestComponent = () => {
+ const { copilotkit } = useCopilotKit();
+ const resourceId = copilotkit.resourceId;
+ return (
+
+
+ );
+
+ expect(container.textContent).toBe("user-1");
+
+ rerender(
+
+
+ );
+
+ expect(container.textContent).toBe("user-1,workspace-1");
+ });
+
+ it("should transition from array to undefined", () => {
+ const TestComponent = () => {
+ const { copilotkit } = useCopilotKit();
+ return
+
+ );
+
+ expect(container.textContent).toBe("defined");
+
+ rerender(
+
+
+ );
+
+ expect(container.textContent).toBe("undefined");
+ });
+ });
+
+ describe("setResourceId hook", () => {
+ it("should expose setResourceId function", () => {
+ const TestComponent = () => {
+ const { setResourceId } = useCopilotKit();
+ return
+
+ );
+
+ expect(container.textContent).toBe("function");
+ });
+
+ it("should update resourceId via setResourceId", async () => {
+ const TestComponent = () => {
+ const { copilotkit, setResourceId } = useCopilotKit();
+ return (
+
+
+ );
+
+ expect(getByTestId("resourceId").textContent).toBe("user-1");
+
+ getByText("Change").click();
+
+ await waitFor(() => {
+ expect(getByTestId("resourceId").textContent).toBe("user-2");
+ });
+ });
+
+ it("should handle setResourceId with array", async () => {
+ const TestComponent = () => {
+ const { copilotkit, setResourceId } = useCopilotKit();
+ const resourceId = copilotkit.resourceId;
+ return (
+
+
+ );
+
+ expect(getByTestId("resourceId").textContent).toBe("user-1");
+
+ getByText("Change").click();
+
+ await waitFor(() => {
+ expect(getByTestId("resourceId").textContent).toBe("user-1,workspace-1");
+ });
+ });
+
+ it("should handle setResourceId with undefined", async () => {
+ const TestComponent = () => {
+ const { copilotkit, setResourceId } = useCopilotKit();
+ return (
+
+
+ );
+
+ expect(getByTestId("resourceId").textContent).toBe("defined");
+
+ getByText("Clear").click();
+
+ await waitFor(() => {
+ expect(getByTestId("resourceId").textContent).toBe("undefined");
+ });
+ });
+
+ it("should handle multiple rapid setResourceId calls", async () => {
+ const TestComponent = () => {
+ const { copilotkit, setResourceId } = useCopilotKit();
+ return (
+
+
+ );
+
+ expect(getByTestId("resourceId").textContent).toBe("user-1");
+
+ getByText("Rapid Change").click();
+
+ // Should end up with the last value
+ await waitFor(() => {
+ expect(getByTestId("resourceId").textContent).toBe("user-4");
+ });
+ });
+ });
+
+ describe("production warnings", () => {
+ it("should log error in production when resourceId is not set", async () => {
+ process.env.NODE_ENV = "production";
+
+ render(
+
+
+ );
+
+ await waitFor(() => {
+ expect(consoleErrorSpy).toHaveBeenCalledWith(
+ expect.stringContaining("Security Warning: No resourceId set in production")
+ );
+ });
+ });
+
+ it("should log warning in development when resourceId is not set", async () => {
+ process.env.NODE_ENV = "development";
+
+ render(
+
+
+ );
+
+ await waitFor(() => {
+ expect(consoleWarnSpy).toHaveBeenCalledWith(
+ expect.stringContaining("No resourceId set")
+ );
+ });
+ });
+
+ it("should not log warnings when resourceId is set", async () => {
+ process.env.NODE_ENV = "production";
+
+ render(
+
+
+ );
+
+ await waitFor(() => {
+ expect(consoleErrorSpy).not.toHaveBeenCalled();
+ expect(consoleWarnSpy).not.toHaveBeenCalled();
+ });
+ });
+
+ it("should handle empty array as 'set' (no warning)", async () => {
+ process.env.NODE_ENV = "production";
+
+ render(
+
+
+ );
+
+ await waitFor(() => {
+ // Empty array is considered "set" even though it grants no access
+ expect(consoleErrorSpy).not.toHaveBeenCalled();
+ });
+ });
+
+ it("should not log warnings on server side (SSR)", async () => {
+ // Note: In jsdom environment, window is always present
+ // This test verifies the typeof check in the code
+ process.env.NODE_ENV = "production";
+
+ render(
+
+
+ );
+
+ // With window present and resourceId undefined, should log error
+ await waitFor(() => {
+ expect(consoleErrorSpy).toHaveBeenCalledWith(
+ expect.stringContaining("Security Warning: No resourceId set in production")
+ );
+ });
+ });
+ });
+
+ describe("edge cases", () => {
+ it("should handle very long resourceId strings", () => {
+ const longId = "user-" + "a".repeat(1000);
+ const TestComponent = () => {
+ const { copilotkit } = useCopilotKit();
+ return
+
+ );
+
+ expect(container.textContent).toBe(String(longId.length));
+ });
+
+ it("should handle array with many resourceIds", () => {
+ const manyIds = Array.from({ length: 100 }, (_, i) => `id-${i}`);
+ const TestComponent = () => {
+ const { copilotkit } = useCopilotKit();
+ const resourceId = copilotkit.resourceId;
+ return
+
+ );
+
+ expect(container.textContent).toBe("100");
+ });
+
+ it("should handle resourceId with only whitespace", () => {
+ const whitespaceId = " ";
+ const TestComponent = () => {
+ const { copilotkit } = useCopilotKit();
+ return
+
+ );
+
+ expect(container.textContent).toBe(whitespaceId);
+ });
+
+ it("should handle array with duplicate resourceIds", () => {
+ const duplicates = ["user-1", "user-1", "user-2", "user-1"];
+ const TestComponent = () => {
+ const { copilotkit } = useCopilotKit();
+ const resourceId = copilotkit.resourceId;
+ return (
+
+
+ );
+
+ // Should preserve duplicates (server may filter)
+ expect(container.textContent).toBe("user-1,user-1,user-2,user-1");
+ });
+
+ it("should handle resourceId with Unicode characters", () => {
+ const unicodeId = "用户-123-مستخدم";
+ const TestComponent = () => {
+ const { copilotkit } = useCopilotKit();
+ return
+
+ );
+
+ expect(container.textContent).toBe(unicodeId);
+ });
+
+ it("should handle array with mixed types (though TypeScript prevents this)", () => {
+ // This tests runtime behavior if TypeScript is bypassed
+ const mixedArray = ["user-1", "workspace-2"] as any;
+ const TestComponent = () => {
+ const { copilotkit } = useCopilotKit();
+ const resourceId = copilotkit.resourceId;
+ return (
+
+
+ );
+
+ expect(container.textContent).toBe("user-1,workspace-2");
+ });
+ });
+
+ describe("context isolation", () => {
+ it("should not share resourceId between different provider instances", () => {
+ const TestComponent = ({ testId }: { testId: string }) => {
+ const { copilotkit } = useCopilotKit();
+ return
+
+
+
+
+ );
+
+ expect(getByTestId("provider1").textContent).toBe("user-1");
+ expect(getByTestId("provider2").textContent).toBe("user-2");
+ });
+ });
+});
diff --git a/packages/react/src/types/web-inspector.d.ts b/packages/react/src/types/web-inspector.d.ts
new file mode 100644
index 00000000..575e602d
--- /dev/null
+++ b/packages/react/src/types/web-inspector.d.ts
@@ -0,0 +1 @@
+declare module "@copilotkitnext/web-inspector";
diff --git a/packages/runtime/src/__tests__/client-declared-resource-id.integration.test.ts b/packages/runtime/src/__tests__/client-declared-resource-id.integration.test.ts
new file mode 100644
index 00000000..4bca5ebb
--- /dev/null
+++ b/packages/runtime/src/__tests__/client-declared-resource-id.integration.test.ts
@@ -0,0 +1,829 @@
+import { describe, expect, it, vi, beforeEach } from "vitest";
+import { CopilotRuntime } from "../runtime";
+import { InMemoryAgentRunner } from "../runner/in-memory";
+import {
+ validateResourceIdMatch,
+ filterAuthorizedResourceIds,
+ createStrictThreadScopeResolver,
+ createFilteringThreadScopeResolver,
+} from "../resource-id-helpers";
+import { handleListThreads } from "../handlers/handle-threads";
+import { handleRunAgent } from "../handlers/handle-run";
+import { EMPTY } from "rxjs";
+import {
+ AbstractAgent,
+ BaseEvent,
+ RunAgentInput,
+ EventType,
+ Message,
+ TextMessageStartEvent,
+ TextMessageContentEvent,
+ TextMessageEndEvent,
+} from "@ag-ui/client";
+
+type RunCallbacks = {
+ onEvent: (event: { event: BaseEvent }) => void;
+ onNewMessage?: (args: { message: Message }) => void;
+ onRunStartedEvent?: () => void;
+};
+
+// Mock agent for testing
+class MockAgent extends AbstractAgent {
+ private events: BaseEvent[];
+
+ constructor(events: BaseEvent[] = []) {
+ super();
+ this.events = events;
+ }
+
+ async runAgent(input: RunAgentInput, callbacks: RunCallbacks): Promise {
+ if (callbacks.onRunStartedEvent) {
+ callbacks.onRunStartedEvent();
+ }
+
+ for (const event of this.events) {
+ callbacks.onEvent({ event });
+ }
+ }
+
+ clone(): AbstractAgent {
+ return new MockAgent(this.events);
+ }
+
+ protected run(): ReturnType {
+ return EMPTY;
+ }
+
+ protected connect(): ReturnType {
+ return EMPTY;
+ }
+}
+
+/**
+ * Integration tests for client-declared resourceId flow.
+ * Tests the full path from client hint → server validation → runner scoping.
+ */
+describe("Client-Declared Resource ID Integration", () => {
+ let runner: InMemoryAgentRunner;
+
+ beforeEach(() => {
+ runner = new InMemoryAgentRunner();
+ runner.clearAllThreads();
+ });
+
+ describe("Header Parsing", () => {
+ it("should parse single resourceId from header", async () => {
+ const extractor = vi.fn(async ({ clientDeclared }) => {
+ expect(clientDeclared).toBe("user-123");
+ return { resourceId: "user-123" };
+ });
+
+ const runtime = new CopilotRuntime({
+ agents: {},
+ resolveThreadsScope: extractor,
+ runner: runner,
+ });
+
+ const request = new Request("https://example.com/api/threads", {
+ headers: {
+ "X-CopilotKit-Resource-ID": "user-123",
+ },
+ });
+
+ await handleListThreads({ runtime, request });
+
+ expect(extractor).toHaveBeenCalledWith({
+ request,
+ clientDeclared: "user-123",
+ });
+ });
+
+ it("should parse array of resourceIds from header", async () => {
+ const extractor = vi.fn(async ({ clientDeclared }) => {
+ expect(clientDeclared).toEqual(["user-123", "workspace-456"]);
+ return { resourceId: ["user-123", "workspace-456"] };
+ });
+
+ const runtime = new CopilotRuntime({
+ agents: {},
+ resolveThreadsScope: extractor,
+ runner: runner,
+ });
+
+ const request = new Request("https://example.com/api/threads", {
+ headers: {
+ "X-CopilotKit-Resource-ID": "user-123,workspace-456",
+ },
+ });
+
+ await handleListThreads({ runtime, request });
+
+ expect(extractor).toHaveBeenCalledWith({
+ request,
+ clientDeclared: ["user-123", "workspace-456"],
+ });
+ });
+
+ it("should handle URI-encoded resourceIds", async () => {
+ const extractor = vi.fn(async ({ clientDeclared }) => {
+ expect(clientDeclared).toBe("user@example.com/workspace#123");
+ return { resourceId: clientDeclared as string };
+ });
+
+ const runtime = new CopilotRuntime({
+ agents: {},
+ resolveThreadsScope: extractor,
+ runner: runner,
+ });
+
+ const request = new Request("https://example.com/api/threads", {
+ headers: {
+ "X-CopilotKit-Resource-ID": "user%40example.com%2Fworkspace%23123",
+ },
+ });
+
+ await handleListThreads({ runtime, request });
+
+ expect(extractor).toHaveBeenCalledOnce();
+ });
+
+ it("should handle missing header (no client hint)", async () => {
+ const extractor = vi.fn(async ({ clientDeclared }) => {
+ expect(clientDeclared).toBeUndefined();
+ return { resourceId: "server-determined" };
+ });
+
+ const runtime = new CopilotRuntime({
+ agents: {},
+ resolveThreadsScope: extractor,
+ runner: runner,
+ });
+
+ const request = new Request("https://example.com/api/threads");
+
+ await handleListThreads({ runtime, request });
+
+ expect(extractor).toHaveBeenCalledWith({
+ request,
+ clientDeclared: undefined,
+ });
+ });
+
+ it("should handle empty header value", async () => {
+ const extractor = vi.fn(async ({ clientDeclared }) => {
+ // Empty string should be treated as single-element array with empty string
+ expect(clientDeclared).toBe("");
+ return { resourceId: "fallback" };
+ });
+
+ const runtime = new CopilotRuntime({
+ agents: {},
+ resolveThreadsScope: extractor,
+ runner: runner,
+ });
+
+ const request = new Request("https://example.com/api/threads", {
+ headers: {
+ "X-CopilotKit-Resource-ID": "",
+ },
+ });
+
+ await handleListThreads({ runtime, request });
+
+ expect(extractor).toHaveBeenCalledOnce();
+ });
+
+ it("should handle whitespace in comma-separated values", async () => {
+ const extractor = vi.fn(async ({ clientDeclared }) => {
+ // Should trim whitespace around values
+ expect(clientDeclared).toEqual(["user-1", "workspace-2", "project-3"]);
+ return { resourceId: clientDeclared as string[] };
+ });
+
+ const runtime = new CopilotRuntime({
+ agents: {},
+ resolveThreadsScope: extractor,
+ runner: runner,
+ });
+
+ const request = new Request("https://example.com/api/threads", {
+ headers: {
+ "X-CopilotKit-Resource-ID": "user-1, workspace-2 , project-3",
+ },
+ });
+
+ await handleListThreads({ runtime, request });
+
+ expect(extractor).toHaveBeenCalledOnce();
+ });
+ });
+
+ describe("Validation Patterns", () => {
+ describe("Strict Validation Pattern", () => {
+ it("should allow matching client-declared ID", async () => {
+ const runtime = new CopilotRuntime({
+ agents: {},
+ resolveThreadsScope: createStrictThreadScopeResolver(async (request) => {
+ // Simulate authentication
+ const authHeader = request.headers.get("Authorization");
+ if (authHeader === "Bearer user-123-token") {
+ return "user-123";
+ }
+ throw new Error("Unauthorized");
+ }),
+ runner: runner,
+ });
+
+ const request = new Request("https://example.com/api/threads", {
+ headers: {
+ Authorization: "Bearer user-123-token",
+ "X-CopilotKit-Resource-ID": "user-123",
+ },
+ });
+
+ const response = await handleListThreads({ runtime, request });
+
+ expect(response.status).toBe(200);
+ });
+
+ it("should reject mismatched client-declared ID", async () => {
+ const runtime = new CopilotRuntime({
+ agents: {},
+ resolveThreadsScope: createStrictThreadScopeResolver(async (request) => {
+ const authHeader = request.headers.get("Authorization");
+ if (authHeader === "Bearer user-123-token") {
+ return "user-123";
+ }
+ throw new Error("Unauthorized");
+ }),
+ runner: runner,
+ });
+
+ const request = new Request("https://example.com/api/threads", {
+ headers: {
+ Authorization: "Bearer user-123-token",
+ "X-CopilotKit-Resource-ID": "user-999", // Wrong ID
+ },
+ });
+
+ const response = await handleListThreads({ runtime, request });
+ expect(response.status).toBe(500);
+ });
+
+ it("should allow undefined client-declared ID", async () => {
+ const runtime = new CopilotRuntime({
+ agents: {},
+ resolveThreadsScope: createStrictThreadScopeResolver(async (request) => {
+ return "user-123";
+ }),
+ runner: runner,
+ });
+
+ const request = new Request("https://example.com/api/threads");
+
+ const response = await handleListThreads({ runtime, request });
+
+ expect(response.status).toBe(200);
+ });
+ });
+
+ describe("Filtering Pattern", () => {
+ it("should filter to authorized workspaces", async () => {
+ const runtime = new CopilotRuntime({
+ agents: {},
+ resolveThreadsScope: createFilteringThreadScopeResolver(async (request) => {
+ // Simulate user with access to specific workspaces
+ return ["workspace-1", "workspace-2", "workspace-3"];
+ }),
+ runner: runner,
+ });
+
+ const request = new Request("https://example.com/api/threads", {
+ headers: {
+ // Client requests workspace-2 and workspace-99
+ "X-CopilotKit-Resource-ID": "workspace-2,workspace-99",
+ },
+ });
+
+ // Should succeed - workspace-2 is authorized
+ const response = await handleListThreads({ runtime, request });
+ expect(response.status).toBe(200);
+
+ // The extractor should have filtered to only workspace-2
+ // (This would be tested by checking what the runner received)
+ });
+
+ it("should reject when no client IDs are authorized", async () => {
+ const runtime = new CopilotRuntime({
+ agents: {},
+ resolveThreadsScope: createFilteringThreadScopeResolver(async (request) => {
+ return ["workspace-1", "workspace-2"];
+ }),
+ runner: runner,
+ });
+
+ const request = new Request("https://example.com/api/threads", {
+ headers: {
+ "X-CopilotKit-Resource-ID": "workspace-99,workspace-88",
+ },
+ });
+
+ const response = await handleListThreads({ runtime, request });
+ expect(response.status).toBe(500);
+ });
+
+ it("should return all authorized when no client hint", async () => {
+ let capturedScope: any;
+ const customRunner = {
+ ...runner,
+ listThreads: async (request: any) => {
+ capturedScope = request.scope;
+ return { threads: [], total: 0 };
+ },
+ };
+
+ const runtime = new CopilotRuntime({
+ agents: {},
+ resolveThreadsScope: createFilteringThreadScopeResolver(async (request) => {
+ return ["workspace-1", "workspace-2", "workspace-3"];
+ }),
+ runner: customRunner as any,
+ });
+
+ const request = new Request("https://example.com/api/threads");
+
+ await handleListThreads({ runtime, request });
+
+ expect(capturedScope.resourceId).toEqual(["workspace-1", "workspace-2", "workspace-3"]);
+ });
+ });
+
+ describe("Manual Validation Pattern", () => {
+ it("should allow custom validation logic", async () => {
+ const runtime = new CopilotRuntime({
+ agents: {},
+ resolveThreadsScope: async ({ request, clientDeclared }) => {
+ // Custom authentication and validation
+ const userId = await authenticateUser(request);
+ const userWorkspaces = await getUserWorkspaces(userId);
+
+ // Custom logic: Allow if client declares their user ID or one of their workspaces
+ if (clientDeclared) {
+ const validIds = [userId, ...userWorkspaces];
+ validateResourceIdMatch(clientDeclared, validIds);
+ return { resourceId: clientDeclared };
+ }
+
+ // No client hint - return all accessible
+ return { resourceId: [userId, ...userWorkspaces] };
+ },
+ runner: runner,
+ });
+
+ const request = new Request("https://example.com/api/threads", {
+ headers: {
+ Authorization: "Bearer user-1-token",
+ "X-CopilotKit-Resource-ID": "workspace-team-a",
+ },
+ });
+
+ const response = await handleListThreads({ runtime, request });
+
+ expect(response.status).toBe(200);
+ });
+
+ it("should reject invalid IDs with custom validation", async () => {
+ const runtime = new CopilotRuntime({
+ agents: {},
+ resolveThreadsScope: async ({ request, clientDeclared }) => {
+ const userId = await authenticateUser(request);
+ const userWorkspaces = await getUserWorkspaces(userId);
+
+ if (clientDeclared) {
+ const validIds = [userId, ...userWorkspaces];
+ validateResourceIdMatch(clientDeclared, validIds);
+ return { resourceId: clientDeclared };
+ }
+
+ return { resourceId: [userId, ...userWorkspaces] };
+ },
+ runner: runner,
+ });
+
+ const request = new Request("https://example.com/api/threads", {
+ headers: {
+ Authorization: "Bearer user-1-token",
+ "X-CopilotKit-Resource-ID": "workspace-unauthorized", // Not in user's workspaces
+ },
+ });
+
+ const response = await handleListThreads({ runtime, request });
+ expect(response.status).toBe(500);
+ });
+ });
+
+ describe("Override Pattern (Ignore Client)", () => {
+ it("should ignore client-declared ID and use server-determined", async () => {
+ let capturedScope: any;
+ const customRunner = {
+ ...runner,
+ listThreads: async (request: any) => {
+ capturedScope = request.scope;
+ return { threads: [], total: 0 };
+ },
+ };
+
+ const runtime = new CopilotRuntime({
+ agents: {},
+ resolveThreadsScope: async ({ request, clientDeclared }) => {
+ // Completely ignore clientDeclared
+ const userId = await authenticateUser(request);
+ return { resourceId: userId };
+ },
+ runner: customRunner as any,
+ });
+
+ const request = new Request("https://example.com/api/threads", {
+ headers: {
+ Authorization: "Bearer user-1-token",
+ "X-CopilotKit-Resource-ID": "user-999", // Should be ignored
+ },
+ });
+
+ await handleListThreads({ runtime, request });
+
+ // Should use server-determined, not client hint
+ expect(capturedScope.resourceId).toBe("user-1");
+ });
+ });
+ });
+
+ describe("Edge Cases", () => {
+ it("should handle empty string values after parsing", async () => {
+ const extractor = vi.fn(async ({ clientDeclared }) => {
+ // Client sent empty string - resolver should handle it
+ expect(clientDeclared).toBe("");
+ // Resolver can choose to reject or provide fallback
+ throw new Error("Empty resource ID not allowed");
+ });
+
+ const runtime = new CopilotRuntime({
+ agents: {},
+ resolveThreadsScope: extractor,
+ runner: runner,
+ });
+
+ const request = new Request("https://example.com/api/threads", {
+ headers: {
+ "X-CopilotKit-Resource-ID": "",
+ },
+ });
+
+ const response = await handleListThreads({ runtime, request });
+ expect(response.status).toBe(500);
+ });
+
+ it("should handle whitespace-only values in comma-separated list", async () => {
+ const extractor = vi.fn(async ({ clientDeclared }) => {
+ // After trimming, we get empty strings
+ expect(clientDeclared).toEqual(["", ""]);
+ // Resolver should validate and reject
+ throw new Error("All resource IDs are empty after trimming");
+ });
+
+ const runtime = new CopilotRuntime({
+ agents: {},
+ resolveThreadsScope: extractor,
+ runner: runner,
+ });
+
+ const request = new Request("https://example.com/api/threads", {
+ headers: {
+ "X-CopilotKit-Resource-ID": " , ",
+ },
+ });
+
+ const response = await handleListThreads({ runtime, request });
+ expect(response.status).toBe(500);
+ });
+
+ it("should handle mixed valid and empty values", async () => {
+ const extractor = vi.fn(async ({ clientDeclared }) => {
+ // Parser returns ["user-1", "", "user-2"]
+ expect(clientDeclared).toEqual(["user-1", "", "user-2"]);
+ // Resolver can filter out empty strings if needed
+ const validIds = Array.isArray(clientDeclared)
+ ? clientDeclared.filter((id) => id.trim().length > 0)
+ : [];
+ if (validIds.length === 0) {
+ throw new Error("No valid resource IDs provided");
+ }
+ return { resourceId: validIds };
+ });
+
+ const runtime = new CopilotRuntime({
+ agents: {},
+ resolveThreadsScope: extractor,
+ runner: runner,
+ });
+
+ const request = new Request("https://example.com/api/threads", {
+ headers: {
+ "X-CopilotKit-Resource-ID": "user-1, ,user-2",
+ },
+ });
+
+ const response = await handleListThreads({ runtime, request });
+ expect(response.status).toBe(200);
+ });
+
+ it("should handle special characters in client-declared ID", async () => {
+ const specialId = "user@example.com/workspace#123";
+ const extractor = vi.fn(async ({ clientDeclared }) => {
+ validateResourceIdMatch(clientDeclared, specialId);
+ return { resourceId: specialId };
+ });
+
+ const runtime = new CopilotRuntime({
+ agents: {},
+ resolveThreadsScope: extractor,
+ runner: runner,
+ });
+
+ const request = new Request("https://example.com/api/threads", {
+ headers: {
+ "X-CopilotKit-Resource-ID": encodeURIComponent(specialId),
+ },
+ });
+
+ const response = await handleListThreads({ runtime, request });
+
+ expect(response.status).toBe(200);
+ });
+
+ it("should handle Unicode characters", async () => {
+ const unicodeId = "用户-123-مستخدم";
+ const extractor = vi.fn(async ({ clientDeclared }) => {
+ expect(clientDeclared).toBe(unicodeId);
+ return { resourceId: unicodeId };
+ });
+
+ const runtime = new CopilotRuntime({
+ agents: {},
+ resolveThreadsScope: extractor,
+ runner: runner,
+ });
+
+ const request = new Request("https://example.com/api/threads", {
+ headers: {
+ "X-CopilotKit-Resource-ID": encodeURIComponent(unicodeId),
+ },
+ });
+
+ await handleListThreads({ runtime, request });
+
+ expect(extractor).toHaveBeenCalledOnce();
+ });
+
+ it("should handle very long resourceId", async () => {
+ const longId = "user-" + "a".repeat(1000);
+ const extractor = vi.fn(async ({ clientDeclared }) => {
+ expect(clientDeclared).toBe(longId);
+ return { resourceId: longId };
+ });
+
+ const runtime = new CopilotRuntime({
+ agents: {},
+ resolveThreadsScope: extractor,
+ runner: runner,
+ });
+
+ const request = new Request("https://example.com/api/threads", {
+ headers: {
+ "X-CopilotKit-Resource-ID": encodeURIComponent(longId),
+ },
+ });
+
+ await handleListThreads({ runtime, request });
+
+ expect(extractor).toHaveBeenCalledOnce();
+ });
+
+ it("should handle many resourceIds in header", async () => {
+ const manyIds = Array.from({ length: 50 }, (_, i) => `id-${i}`);
+ const extractor = vi.fn(async ({ clientDeclared }) => {
+ expect(clientDeclared).toEqual(manyIds);
+ return { resourceId: filterAuthorizedResourceIds(clientDeclared, manyIds) };
+ });
+
+ const runtime = new CopilotRuntime({
+ agents: {},
+ resolveThreadsScope: extractor,
+ runner: runner,
+ });
+
+ const request = new Request("https://example.com/api/threads", {
+ headers: {
+ "X-CopilotKit-Resource-ID": manyIds.map((id) => encodeURIComponent(id)).join(","),
+ },
+ });
+
+ await handleListThreads({ runtime, request });
+
+ expect(extractor).toHaveBeenCalledOnce();
+ });
+ });
+
+ describe("Security: Malicious Client Cannot Widen Access", () => {
+ it("should enforce server-determined scope even when client claims different resource", async () => {
+ // This is the critical security test:
+ // A malicious client tries to access another user's threads by sending a fake header.
+ // The server must enforce the authenticated user's actual scope.
+
+ const createTestEvents = (messageText: string, messageId: string): BaseEvent[] => [
+ { type: EventType.TEXT_MESSAGE_START, messageId, role: "user" } as TextMessageStartEvent,
+ { type: EventType.TEXT_MESSAGE_CONTENT, messageId, delta: messageText } as TextMessageContentEvent,
+ { type: EventType.TEXT_MESSAGE_END, messageId } as TextMessageEndEvent,
+ ];
+
+ const mockAgent = new MockAgent(createTestEvents("Test message", "msg1"));
+
+ // Use strict validation pattern to enforce mismatch detection
+ const runtime = new CopilotRuntime({
+ agents: { default: mockAgent },
+ resolveThreadsScope: createStrictThreadScopeResolver(async (request) => {
+ // Authenticate the user from the request (e.g., JWT token)
+ const token = request.headers.get("Authorization");
+ if (token === "Bearer alice-token") {
+ return "user-alice";
+ }
+ if (token === "Bearer bob-token") {
+ return "user-bob";
+ }
+ throw new Error("Unauthorized");
+ }),
+ runner: runner,
+ });
+
+ // Alice creates a thread with her correct token and ID
+ const createRequest = new Request("http://localhost/api/copilotkit/run/default", {
+ method: "POST",
+ body: JSON.stringify({
+ threadId: "alice-thread-123",
+ runId: "run-1",
+ messages: [],
+ state: {},
+ }),
+ headers: {
+ "Content-Type": "application/json",
+ Authorization: "Bearer alice-token",
+ "X-CopilotKit-Resource-ID": "user-alice",
+ },
+ });
+
+ const createResponse = await handleRunAgent({
+ runtime,
+ request: createRequest,
+ agentId: "default",
+ });
+ expect(createResponse.status).toBe(200);
+
+ // Wait for thread to be created
+ await new Promise((resolve) => setTimeout(resolve, 200));
+
+ // Malicious attempt 1: Bob tries to claim Alice's ID
+ const maliciousRequest1 = new Request("https://example.com/api/threads", {
+ headers: {
+ Authorization: "Bearer bob-token", // Bob's auth
+ "X-CopilotKit-Resource-ID": "user-alice", // Claims Alice's ID
+ },
+ });
+
+ // Should reject because token says "bob" but header says "alice"
+ const response1 = await handleListThreads({ runtime, request: maliciousRequest1 });
+ expect(response1.status).toBe(500);
+
+ // Malicious attempt 2: Alice's token but claims Bob's ID
+ // Server returns alice's scope, which means Bob won't see Alice's threads
+ const maliciousRequest2 = new Request("https://example.com/api/threads", {
+ headers: {
+ Authorization: "Bearer alice-token", // Alice's auth
+ "X-CopilotKit-Resource-ID": "user-bob", // Claims Bob's ID
+ },
+ });
+
+ // Should reject because token says "alice" but header says "bob"
+ const response2 = await handleListThreads({ runtime, request: maliciousRequest2 });
+ expect(response2.status).toBe(500);
+ });
+
+ it("should prove runner stores threads with resolver resourceId, not client hint", async () => {
+ // This test PROVES that threads are stored using the resolver's decision, not the client's claim.
+ // Even if client claims "attacker-user", server enforces "real-user" based on auth.
+
+ // Track what scope was actually passed to the runner
+ let capturedScope: any = null;
+ const customRunner = {
+ ...runner,
+ listThreads: async (request: any) => {
+ capturedScope = request.scope;
+ return runner.listThreads(request);
+ },
+ };
+
+ const runtime = new CopilotRuntime({
+ agents: {},
+ resolveThreadsScope: async ({ request, clientDeclared }) => {
+ // Client claims "attacker-user"
+ expect(clientDeclared).toBe("attacker-user");
+
+ // But server checks auth and determines actual user
+ const token = request.headers.get("Authorization");
+ if (token === "Bearer real-user-token") {
+ // Server OVERRIDES client claim with authenticated user
+ return { resourceId: "real-user" };
+ }
+ throw new Error("Unauthorized");
+ },
+ runner: Promise.resolve(customRunner as any),
+ });
+
+ const request = new Request("https://example.com/api/threads", {
+ headers: {
+ Authorization: "Bearer real-user-token",
+ "X-CopilotKit-Resource-ID": "attacker-user", // Malicious claim
+ },
+ });
+
+ const response = await handleListThreads({ runtime, request });
+ expect(response.status).toBe(200);
+
+ // CRITICAL ASSERTION: Runner received "real-user" from resolver, not "attacker-user" from client
+ expect(capturedScope).not.toBeNull();
+ expect(capturedScope.resourceId).toBe("real-user");
+ expect(capturedScope.resourceId).not.toBe("attacker-user");
+
+ // This proves the security model: client hints cannot widen access.
+ // The resolver's decision is what gets stored and enforced.
+ });
+ });
+
+ describe("Backward Compatibility", () => {
+ it("should work without client-declared resourceId (legacy behavior)", async () => {
+ const runtime = new CopilotRuntime({
+ agents: {},
+ resolveThreadsScope: async ({ request }) => {
+ // Old-style extractor ignoring clientDeclared
+ const token = request.headers.get("Authorization");
+ if (token === "Bearer user-123-token") {
+ return { resourceId: "user-123" };
+ }
+ throw new Error("Unauthorized");
+ },
+ runner: runner,
+ });
+
+ const request = new Request("https://example.com/api/threads", {
+ headers: {
+ Authorization: "Bearer user-123-token",
+ },
+ });
+
+ const response = await handleListThreads({ runtime, request });
+
+ expect(response.status).toBe(200);
+ });
+
+ it("should work with GLOBAL_SCOPE pattern", async () => {
+ const runtime = new CopilotRuntime({
+ agents: {},
+ resolveThreadsScope: CopilotRuntime.GLOBAL_SCOPE,
+ runner: runner,
+ });
+
+ const request = new Request("https://example.com/api/threads", {
+ headers: {
+ "X-CopilotKit-Resource-ID": "user-123",
+ },
+ });
+
+ const response = await handleListThreads({ runtime, request });
+
+ expect(response.status).toBe(200);
+ });
+ });
+});
+
+// Helper functions simulating authentication/authorization
+async function authenticateUser(request: Request): Promise {
+ const token = request.headers.get("Authorization");
+ if (token === "Bearer user-1-token") return "user-1";
+ if (token === "Bearer user-2-token") return "user-2";
+ throw new Error("Invalid token");
+}
+
+async function getUserWorkspaces(userId: string): Promise {
+ if (userId === "user-1") return ["workspace-team-a", "workspace-personal"];
+ if (userId === "user-2") return ["workspace-team-b"];
+ return [];
+}
diff --git a/packages/runtime/src/__tests__/handle-run.test.ts b/packages/runtime/src/__tests__/handle-run.test.ts
index 570c7fba..927d2d51 100644
--- a/packages/runtime/src/__tests__/handle-run.test.ts
+++ b/packages/runtime/src/__tests__/handle-run.test.ts
@@ -5,14 +5,13 @@ import { handleRunAgent } from "../handlers/handle-run";
import { CopilotRuntime } from "../runtime";
describe("handleRunAgent", () => {
- const createMockRuntime = (
- agents: Record = {}
- ): CopilotRuntime => {
+ const createMockRuntime = (agents: Record = {}): CopilotRuntime => {
return {
agents: Promise.resolve(agents),
transcriptionService: undefined,
beforeRequestMiddleware: undefined,
afterRequestMiddleware: undefined,
+ resolveThreadsScope: async () => ({ resourceId: "test-user" }),
} as CopilotRuntime;
};
@@ -49,6 +48,7 @@ describe("handleRunAgent", () => {
transcriptionService: undefined,
beforeRequestMiddleware: undefined,
afterRequestMiddleware: undefined,
+ resolveThreadsScope: async () => ({ resourceId: "test-user" }),
} as CopilotRuntime;
const request = createMockRequest();
const agentId = "test-agent";
@@ -104,6 +104,7 @@ describe("handleRunAgent", () => {
transcriptionService: undefined,
beforeRequestMiddleware: undefined,
afterRequestMiddleware: undefined,
+ resolveThreadsScope: async () => ({ resourceId: "test-user" }),
runner: {
run: ({ agent }: { agent: AbstractAgent }) =>
new Observable((subscriber) => {
diff --git a/packages/runtime/src/__tests__/handle-stop.test.ts b/packages/runtime/src/__tests__/handle-stop.test.ts
new file mode 100644
index 00000000..45aff5d1
--- /dev/null
+++ b/packages/runtime/src/__tests__/handle-stop.test.ts
@@ -0,0 +1,214 @@
+import { describe, expect, it, vi } from "vitest";
+import { handleStopAgent } from "../handlers/handle-stop";
+import type { CopilotRuntime } from "../runtime";
+
+describe("handleStopAgent", () => {
+ const createRequest = () =>
+ new Request("https://example.com/api/copilotkit/stop", {
+ method: "POST",
+ });
+
+ it("returns 404 when agent does not exist", async () => {
+ const runtime = {
+ agents: Promise.resolve({}),
+ runner: Promise.resolve({
+ stop: vi.fn(),
+ }),
+ resolveThreadsScope: async () => ({ resourceId: "test-user" }),
+ } as unknown as CopilotRuntime;
+
+ const response = await handleStopAgent({
+ runtime,
+ request: createRequest(),
+ agentId: "nonexistent-agent",
+ threadId: "thread-123",
+ });
+
+ expect(response.status).toBe(404);
+
+ const data = await response.json();
+ expect(data.error).toBe("Agent not found");
+ });
+
+ it("returns 401 when resolveThreadsScope returns undefined (auth failure)", async () => {
+ const stop = vi.fn();
+ const getThreadMetadata = vi.fn();
+ const runtime = {
+ agents: Promise.resolve({
+ "test-agent": {},
+ }),
+ runner: Promise.resolve({
+ stop,
+ getThreadMetadata,
+ }),
+ resolveThreadsScope: async () => undefined, // Auth failure or missing return
+ } as unknown as CopilotRuntime;
+
+ const response = await handleStopAgent({
+ runtime,
+ request: createRequest(),
+ agentId: "test-agent",
+ threadId: "thread-123",
+ });
+
+ expect(response.status).toBe(401);
+ expect(getThreadMetadata).not.toHaveBeenCalled(); // Should not reach metadata check
+ expect(stop).not.toHaveBeenCalled(); // Should not reach stop
+
+ const data = await response.json();
+ expect(data.error).toBe("Unauthorized");
+ expect(data.message).toBe("No resource scope provided");
+ });
+
+ it("returns 404 when thread does not exist or user lacks access", async () => {
+ const stop = vi.fn();
+ const getThreadMetadata = vi.fn().mockResolvedValue(null);
+ const runtime = {
+ agents: Promise.resolve({
+ "test-agent": {},
+ }),
+ runner: Promise.resolve({
+ stop,
+ getThreadMetadata,
+ }),
+ resolveThreadsScope: async () => ({ resourceId: "test-user" }),
+ } as unknown as CopilotRuntime;
+
+ const response = await handleStopAgent({
+ runtime,
+ request: createRequest(),
+ agentId: "test-agent",
+ threadId: "thread-123",
+ });
+
+ expect(response.status).toBe(404);
+ expect(getThreadMetadata).toHaveBeenCalledWith("thread-123", { resourceId: "test-user" });
+ expect(stop).not.toHaveBeenCalled(); // Should not reach stop if thread not found
+
+ const data = await response.json();
+ expect(data.error).toBe("Thread not found");
+ });
+
+ it("stops the agent successfully when authorized", async () => {
+ const stop = vi.fn().mockResolvedValue(true);
+ const getThreadMetadata = vi.fn().mockResolvedValue({
+ threadId: "thread-123",
+ resourceId: "test-user",
+ });
+ const runtime = {
+ agents: Promise.resolve({
+ "test-agent": {},
+ }),
+ runner: Promise.resolve({
+ stop,
+ getThreadMetadata,
+ }),
+ resolveThreadsScope: async () => ({ resourceId: "test-user" }),
+ } as unknown as CopilotRuntime;
+
+ const response = await handleStopAgent({
+ runtime,
+ request: createRequest(),
+ agentId: "test-agent",
+ threadId: "thread-123",
+ });
+
+ expect(response.status).toBe(200);
+ expect(getThreadMetadata).toHaveBeenCalledWith("thread-123", { resourceId: "test-user" });
+ expect(stop).toHaveBeenCalledWith({ threadId: "thread-123" });
+
+ const data = await response.json();
+ expect(data.stopped).toBe(true);
+ expect(data.interrupt).toBeDefined();
+ });
+
+ it("returns 200 with stopped: false when no active run exists", async () => {
+ const stop = vi.fn().mockResolvedValue(false);
+ const getThreadMetadata = vi.fn().mockResolvedValue({
+ threadId: "thread-123",
+ resourceId: "test-user",
+ });
+ const runtime = {
+ agents: Promise.resolve({
+ "test-agent": {},
+ }),
+ runner: Promise.resolve({
+ stop,
+ getThreadMetadata,
+ }),
+ resolveThreadsScope: async () => ({ resourceId: "test-user" }),
+ } as unknown as CopilotRuntime;
+
+ const response = await handleStopAgent({
+ runtime,
+ request: createRequest(),
+ agentId: "test-agent",
+ threadId: "thread-123",
+ });
+
+ expect(response.status).toBe(200);
+ expect(getThreadMetadata).toHaveBeenCalledWith("thread-123", { resourceId: "test-user" });
+ expect(stop).toHaveBeenCalledWith({ threadId: "thread-123" });
+
+ const data = await response.json();
+ expect(data.stopped).toBe(false);
+ });
+
+ it("allows admin (null scope) to stop any thread", async () => {
+ const stop = vi.fn().mockResolvedValue(true);
+ const getThreadMetadata = vi.fn().mockResolvedValue({
+ threadId: "thread-123",
+ resourceId: "other-user", // Different user
+ });
+ const runtime = {
+ agents: Promise.resolve({
+ "test-agent": {},
+ }),
+ runner: Promise.resolve({
+ stop,
+ getThreadMetadata,
+ }),
+ resolveThreadsScope: async () => null, // Admin bypass
+ } as unknown as CopilotRuntime;
+
+ const response = await handleStopAgent({
+ runtime,
+ request: createRequest(),
+ agentId: "test-agent",
+ threadId: "thread-123",
+ });
+
+ expect(response.status).toBe(200);
+ expect(getThreadMetadata).toHaveBeenCalledWith("thread-123", null);
+ expect(stop).toHaveBeenCalledWith({ threadId: "thread-123" });
+ });
+
+ it("prevents user from stopping another user's thread", async () => {
+ const stop = vi.fn();
+ const getThreadMetadata = vi.fn().mockResolvedValue(null); // Returns null when scope doesn't match
+ const runtime = {
+ agents: Promise.resolve({
+ "test-agent": {},
+ }),
+ runner: Promise.resolve({
+ stop,
+ getThreadMetadata,
+ }),
+ resolveThreadsScope: async () => ({ resourceId: "attacker-user" }),
+ } as unknown as CopilotRuntime;
+
+ const response = await handleStopAgent({
+ runtime,
+ request: createRequest(),
+ agentId: "test-agent",
+ threadId: "victim-thread",
+ });
+
+ expect(response.status).toBe(404); // Not 403, to prevent enumeration
+ expect(getThreadMetadata).toHaveBeenCalledWith("victim-thread", { resourceId: "attacker-user" });
+ expect(stop).not.toHaveBeenCalled(); // Should not reach stop
+
+ const data = await response.json();
+ expect(data.error).toBe("Thread not found");
+ });
+});
diff --git a/packages/runtime/src/__tests__/handle-threads.test.ts b/packages/runtime/src/__tests__/handle-threads.test.ts
new file mode 100644
index 00000000..39ff28d4
--- /dev/null
+++ b/packages/runtime/src/__tests__/handle-threads.test.ts
@@ -0,0 +1,323 @@
+import { describe, expect, it, vi } from "vitest";
+import { handleListThreads, handleGetThread, handleDeleteThread } from "../handlers/handle-threads";
+import type { CopilotRuntime } from "../runtime";
+
+const createRuntime = (listThreads = vi.fn().mockResolvedValue({ threads: [], total: 0 })) =>
+ ({
+ runner: Promise.resolve({
+ listThreads,
+ }),
+ resolveThreadsScope: async () => ({ resourceId: "test-user" }),
+ }) as unknown as CopilotRuntime;
+
+const createRequest = (search = "") =>
+ new Request(`https://example.com/api/threads${search.startsWith("?") ? search : `?${search}`}`, {
+ method: "GET",
+ });
+
+describe("handleListThreads", () => {
+ it("uses defaults when limit and offset are missing", async () => {
+ const listThreads = vi.fn().mockResolvedValue({ threads: [], total: 0 });
+ const runtime = createRuntime(listThreads);
+
+ const response = await handleListThreads({
+ runtime,
+ request: createRequest(""),
+ });
+
+ expect(listThreads).toHaveBeenCalledWith({ scope: { resourceId: "test-user" }, limit: 20, offset: 0 });
+ expect(response.status).toBe(200);
+ });
+
+ it("falls back to defaults when params are invalid", async () => {
+ const listThreads = vi.fn().mockResolvedValue({ threads: [], total: 0 });
+ const runtime = createRuntime(listThreads);
+
+ await handleListThreads({
+ runtime,
+ request: createRequest("?limit=abc&offset=oops"),
+ });
+
+ expect(listThreads).toHaveBeenCalledWith({ scope: { resourceId: "test-user" }, limit: 20, offset: 0 });
+ });
+
+ it("normalises negative values", async () => {
+ const listThreads = vi.fn().mockResolvedValue({ threads: [], total: 0 });
+ const runtime = createRuntime(listThreads);
+
+ await handleListThreads({
+ runtime,
+ request: createRequest("?limit=-10&offset=-5"),
+ });
+
+ expect(listThreads).toHaveBeenCalledWith({ scope: { resourceId: "test-user" }, limit: 1, offset: 0 });
+ });
+
+ it("caps the limit at 100", async () => {
+ const listThreads = vi.fn().mockResolvedValue({ threads: [], total: 0 });
+ const runtime = createRuntime(listThreads);
+
+ await handleListThreads({
+ runtime,
+ request: createRequest("?limit=99999&offset=10"),
+ });
+
+ expect(listThreads).toHaveBeenCalledWith({ scope: { resourceId: "test-user" }, limit: 100, offset: 10 });
+ });
+
+ it("returns 401 when resolveThreadsScope returns undefined (auth failure)", async () => {
+ const listThreads = vi.fn().mockResolvedValue({ threads: [], total: 0 });
+ const runtime = {
+ runner: Promise.resolve({
+ listThreads,
+ }),
+ resolveThreadsScope: async () => undefined, // Auth failure or missing return
+ } as unknown as CopilotRuntime;
+
+ const response = await handleListThreads({
+ runtime,
+ request: createRequest(""),
+ });
+
+ expect(response.status).toBe(401);
+ expect(listThreads).not.toHaveBeenCalled(); // Should not reach runner
+
+ const data = await response.json();
+ expect(data.error).toBe("Unauthorized");
+ expect(data.message).toBe("No resource scope provided");
+ });
+});
+
+describe("handleGetThread", () => {
+ it("returns 200 with thread metadata when thread exists", async () => {
+ const mockMetadata = {
+ threadId: "thread-123",
+ createdAt: Date.now(),
+ lastActivityAt: Date.now(),
+ isRunning: false,
+ messageCount: 5,
+ firstMessage: "Hello world",
+ resourceId: "test-user",
+ };
+
+ const getThreadMetadata = vi.fn().mockResolvedValue(mockMetadata);
+ const runtime = {
+ runner: Promise.resolve({
+ getThreadMetadata,
+ }),
+ resolveThreadsScope: async () => ({ resourceId: "test-user" }),
+ } as unknown as CopilotRuntime;
+
+ const response = await handleGetThread({
+ runtime,
+ request: new Request("https://example.com/api/threads/thread-123"),
+ threadId: "thread-123",
+ });
+
+ expect(response.status).toBe(200);
+ expect(getThreadMetadata).toHaveBeenCalledWith("thread-123", { resourceId: "test-user" });
+
+ const data = await response.json();
+ expect(data).toEqual(mockMetadata);
+ });
+
+ it("returns 404 when thread does not exist", async () => {
+ const getThreadMetadata = vi.fn().mockResolvedValue(null);
+ const runtime = {
+ runner: Promise.resolve({
+ getThreadMetadata,
+ }),
+ resolveThreadsScope: async () => ({ resourceId: "test-user" }),
+ } as unknown as CopilotRuntime;
+
+ const response = await handleGetThread({
+ runtime,
+ request: new Request("https://example.com/api/threads/nonexistent"),
+ threadId: "nonexistent",
+ });
+
+ expect(response.status).toBe(404);
+
+ const data = await response.json();
+ expect(data.error).toBe("Thread not found");
+ });
+
+ it("returns 404 when thread exists but user lacks access (scope mismatch)", async () => {
+ // Thread exists but belongs to different user
+ const getThreadMetadata = vi.fn().mockResolvedValue(null);
+ const runtime = {
+ runner: Promise.resolve({
+ getThreadMetadata,
+ }),
+ resolveThreadsScope: async () => ({ resourceId: "other-user" }),
+ } as unknown as CopilotRuntime;
+
+ const response = await handleGetThread({
+ runtime,
+ request: new Request("https://example.com/api/threads/thread-123"),
+ threadId: "thread-123",
+ });
+
+ expect(response.status).toBe(404);
+ expect(getThreadMetadata).toHaveBeenCalledWith("thread-123", { resourceId: "other-user" });
+ });
+
+ it("returns 500 when runner throws an error", async () => {
+ const getThreadMetadata = vi.fn().mockRejectedValue(new Error("Database connection failed"));
+ const runtime = {
+ runner: Promise.resolve({
+ getThreadMetadata,
+ }),
+ resolveThreadsScope: async () => ({ resourceId: "test-user" }),
+ } as unknown as CopilotRuntime;
+
+ const response = await handleGetThread({
+ runtime,
+ request: new Request("https://example.com/api/threads/thread-123"),
+ threadId: "thread-123",
+ });
+
+ expect(response.status).toBe(500);
+
+ const data = await response.json();
+ expect(data.error).toBeDefined();
+ });
+
+ it("enforces scope with null (admin bypass)", async () => {
+ const mockMetadata = {
+ threadId: "thread-123",
+ createdAt: Date.now(),
+ lastActivityAt: Date.now(),
+ isRunning: false,
+ messageCount: 5,
+ firstMessage: "Hello world",
+ resourceId: "any-user",
+ };
+
+ const getThreadMetadata = vi.fn().mockResolvedValue(mockMetadata);
+ const runtime = {
+ runner: Promise.resolve({
+ getThreadMetadata,
+ }),
+ resolveThreadsScope: async () => null, // Admin bypass
+ } as unknown as CopilotRuntime;
+
+ const response = await handleGetThread({
+ runtime,
+ request: new Request("https://example.com/api/threads/thread-123"),
+ threadId: "thread-123",
+ });
+
+ expect(response.status).toBe(200);
+ expect(getThreadMetadata).toHaveBeenCalledWith("thread-123", null);
+ });
+
+ it("returns 401 when resolveThreadsScope returns undefined (auth failure)", async () => {
+ const getThreadMetadata = vi.fn().mockResolvedValue({ threadId: "thread-123" });
+ const runtime = {
+ runner: Promise.resolve({
+ getThreadMetadata,
+ }),
+ resolveThreadsScope: async () => undefined, // Auth failure or missing return
+ } as unknown as CopilotRuntime;
+
+ const response = await handleGetThread({
+ runtime,
+ request: new Request("https://example.com/api/threads/thread-123"),
+ threadId: "thread-123",
+ });
+
+ expect(response.status).toBe(401);
+ expect(getThreadMetadata).not.toHaveBeenCalled(); // Should not reach runner
+
+ const data = await response.json();
+ expect(data.error).toBe("Unauthorized");
+ expect(data.message).toBe("No resource scope provided");
+ });
+});
+
+describe("handleDeleteThread", () => {
+ const createDeleteRequest = () =>
+ new Request("https://example.com/api/threads/thread-1", {
+ method: "DELETE",
+ });
+
+ it("returns 400 when thread id is missing", async () => {
+ const runtime = {
+ runner: Promise.resolve({
+ deleteThread: vi.fn(),
+ }),
+ resolveThreadsScope: async () => ({ resourceId: "test-user" }),
+ } as unknown as CopilotRuntime;
+
+ const response = await handleDeleteThread({
+ runtime,
+ request: createDeleteRequest(),
+ threadId: "",
+ });
+
+ expect(response.status).toBe(400);
+ });
+
+ it("deletes thread successfully", async () => {
+ const deleteThread = vi.fn().mockResolvedValue(undefined);
+ const runtime = {
+ runner: Promise.resolve({
+ deleteThread,
+ }),
+ resolveThreadsScope: async () => ({ resourceId: "test-user" }),
+ } as unknown as CopilotRuntime;
+
+ const response = await handleDeleteThread({
+ runtime,
+ request: createDeleteRequest(),
+ threadId: "thread-1",
+ });
+
+ expect(deleteThread).toHaveBeenCalledWith("thread-1", { resourceId: "test-user" });
+ expect(response.status).toBe(200);
+ expect(await response.json()).toEqual({ success: true });
+ });
+
+ it("returns 500 when deletion fails", async () => {
+ const deleteThread = vi.fn().mockRejectedValue(new Error("boom"));
+ const runtime = {
+ runner: Promise.resolve({
+ deleteThread,
+ }),
+ resolveThreadsScope: async () => ({ resourceId: "test-user" }),
+ } as unknown as CopilotRuntime;
+
+ const response = await handleDeleteThread({
+ runtime,
+ request: createDeleteRequest(),
+ threadId: "thread-1",
+ });
+
+ expect(deleteThread).toHaveBeenCalledWith("thread-1", { resourceId: "test-user" });
+ expect(response.status).toBe(500);
+ });
+
+ it("returns 401 when resolveThreadsScope returns undefined (auth failure)", async () => {
+ const deleteThread = vi.fn().mockResolvedValue(undefined);
+ const runtime = {
+ runner: Promise.resolve({
+ deleteThread,
+ }),
+ resolveThreadsScope: async () => undefined, // Auth failure or missing return
+ } as unknown as CopilotRuntime;
+
+ const response = await handleDeleteThread({
+ runtime,
+ request: createDeleteRequest(),
+ threadId: "thread-1",
+ });
+
+ expect(response.status).toBe(401);
+ expect(deleteThread).not.toHaveBeenCalled(); // Should not reach runner
+
+ const data = await response.json();
+ expect(data.error).toBe("Unauthorized");
+ expect(data.message).toBe("No resource scope provided");
+ });
+});
diff --git a/packages/runtime/src/__tests__/in-process-agent-runner.test.ts b/packages/runtime/src/__tests__/in-process-agent-runner.test.ts
index fd4d0e6b..c4b71037 100644
--- a/packages/runtime/src/__tests__/in-process-agent-runner.test.ts
+++ b/packages/runtime/src/__tests__/in-process-agent-runner.test.ts
@@ -5,9 +5,7 @@ import { firstValueFrom } from "rxjs";
import { toArray } from "rxjs/operators";
const stripTerminalEvents = (events: BaseEvent[]) =>
- events.filter(
- (event) => event.type !== EventType.RUN_FINISHED && event.type !== EventType.RUN_ERROR,
- );
+ events.filter((event) => event.type !== EventType.RUN_FINISHED && event.type !== EventType.RUN_ERROR);
// Mock agent implementations for testing
class MockAgent extends AbstractAgent {
@@ -20,10 +18,7 @@ class MockAgent extends AbstractAgent {
this.delay = delay;
}
- async runAgent(
- input: RunAgentInput,
- options: { onEvent: (event: { event: BaseEvent }) => void }
- ): Promise {
+ async runAgent(input: RunAgentInput, options: { onEvent: (event: { event: BaseEvent }) => void }): Promise {
for (const event of this.events) {
if (this.delay > 0) {
await new Promise((resolve) => setTimeout(resolve, this.delay));
@@ -49,10 +44,7 @@ class DelayedEventAgent extends AbstractAgent {
this.prefix = prefix;
}
- async runAgent(
- input: RunAgentInput,
- options: { onEvent: (event: { event: BaseEvent }) => void }
- ): Promise {
+ async runAgent(input: RunAgentInput, options: { onEvent: (event: { event: BaseEvent }) => void }): Promise {
for (let i = 0; i < this.eventCount; i++) {
await new Promise((resolve) => setTimeout(resolve, this.eventDelay));
options.onEvent({
@@ -60,8 +52,8 @@ class DelayedEventAgent extends AbstractAgent {
type: "message",
id: `${this.prefix}-${i}`,
timestamp: new Date().toISOString(),
- data: { index: i, prefix: this.prefix }
- } as BaseEvent
+ data: { index: i, prefix: this.prefix },
+ } as BaseEvent,
});
}
}
@@ -81,18 +73,15 @@ class ErrorThrowingAgent extends AbstractAgent {
this.errorMessage = errorMessage;
}
- async runAgent(
- input: RunAgentInput,
- options: { onEvent: (event: { event: BaseEvent }) => void }
- ): Promise {
+ async runAgent(input: RunAgentInput, options: { onEvent: (event: { event: BaseEvent }) => void }): Promise {
for (let i = 0; i < this.throwAfterEvents; i++) {
options.onEvent({
event: {
type: "message",
id: `error-agent-${i}`,
timestamp: new Date().toISOString(),
- data: { index: i }
- } as BaseEvent
+ data: { index: i },
+ } as BaseEvent,
});
}
throw new Error(this.errorMessage);
@@ -112,10 +101,7 @@ class StoppableAgent extends AbstractAgent {
this.eventDelay = eventDelay;
}
- async runAgent(
- input: RunAgentInput,
- options: { onEvent: (event: { event: BaseEvent }) => void }
- ): Promise {
+ async runAgent(input: RunAgentInput, options: { onEvent: (event: { event: BaseEvent }) => void }): Promise {
this.shouldStop = false;
let counter = 0;
@@ -144,10 +130,7 @@ class StoppableAgent extends AbstractAgent {
class OpenEventsAgent extends AbstractAgent {
private shouldStop = false;
- async runAgent(
- input: RunAgentInput,
- options: { onEvent: (event: { event: BaseEvent }) => void }
- ): Promise {
+ async runAgent(input: RunAgentInput, options: { onEvent: (event: { event: BaseEvent }) => void }): Promise {
this.shouldStop = false;
const messageId = "open-message";
const toolCallId = "open-tool";
@@ -199,25 +182,22 @@ class MultiEventAgent extends AbstractAgent {
this.runId = runId;
}
- async runAgent(
- input: RunAgentInput,
- options: { onEvent: (event: { event: BaseEvent }) => void }
- ): Promise {
+ async runAgent(input: RunAgentInput, options: { onEvent: (event: { event: BaseEvent }) => void }): Promise {
// Emit different types of events
const eventTypes = ["start", "message", "tool_call", "tool_result", "end"];
-
+
for (const eventType of eventTypes) {
options.onEvent({
event: {
type: eventType,
id: `${this.runId}-${eventType}`,
timestamp: new Date().toISOString(),
- data: {
+ data: {
runId: this.runId,
eventType,
- metadata: { source: "MultiEventAgent" }
- }
- } as BaseEvent
+ metadata: { source: "MultiEventAgent" },
+ },
+ } as BaseEvent,
});
}
}
@@ -289,7 +269,7 @@ describe("InMemoryAgentRunner", () => {
describe("Multiple Runs", () => {
it("should accumulate events from multiple sequential runs on same thread", async () => {
const threadId = "test-thread-multi-1";
-
+
// First run
const agent1 = new MultiEventAgent("run-1");
const input1: RunAgentInput = {
@@ -351,7 +331,7 @@ describe("InMemoryAgentRunner", () => {
it("should handle connect during multiple runs", async () => {
const threadId = "test-thread-multi-2";
-
+
// Start first run
const agent1 = new DelayedEventAgent(5, 20, "first");
const input1: RunAgentInput = {
@@ -364,7 +344,7 @@ describe("InMemoryAgentRunner", () => {
const run1Observable = runner.run({ threadId, agent: agent1, input: input1 });
// Wait a bit to ensure first run is in progress
- await new Promise(resolve => setTimeout(resolve, 50));
+ await new Promise((resolve) => setTimeout(resolve, 50));
// Connect during first run
const connectObservable = runner.connect({ threadId });
@@ -402,7 +382,7 @@ describe("InMemoryAgentRunner", () => {
it("should preserve event order across different agent types", async () => {
const threadId = "test-thread-multi-3";
-
+
// Run different types of agents
const agents = [
new MockAgent([
@@ -491,13 +471,13 @@ describe("InMemoryAgentRunner", () => {
runner.run({ threadId, agent, input });
// Connect at different times during the run
- await new Promise(resolve => setTimeout(resolve, 50)); // After ~2 events
+ await new Promise((resolve) => setTimeout(resolve, 50)); // After ~2 events
const connect1 = runner.connect({ threadId });
-
- await new Promise(resolve => setTimeout(resolve, 60)); // After ~5 events
+
+ await new Promise((resolve) => setTimeout(resolve, 60)); // After ~5 events
const connect2 = runner.connect({ threadId });
- await new Promise(resolve => setTimeout(resolve, 80)); // After ~9 events
+ await new Promise((resolve) => setTimeout(resolve, 80)); // After ~9 events
const connect3 = runner.connect({ threadId });
const [events1, events2, events3] = await Promise.all([
@@ -515,8 +495,8 @@ describe("InMemoryAgentRunner", () => {
expect(agentEvents3).toHaveLength(10);
// Verify they all have the same events
- expect(events1.map(e => e.id)).toEqual(events2.map(e => e.id));
- expect(events2.map(e => e.id)).toEqual(events3.map(e => e.id));
+ expect(events1.map((e) => e.id)).toEqual(events2.map((e) => e.id));
+ expect(events2.map((e) => e.id)).toEqual(events3.map((e) => e.id));
});
});
@@ -598,7 +578,7 @@ describe("InMemoryAgentRunner", () => {
// Run and wait for completion (even with error)
const runObservable = runner.run({ threadId, agent, input });
await firstValueFrom(runObservable.pipe(toArray()));
-
+
// Verify thread is not running
const isRunning = await runner.isRunning({ threadId });
expect(isRunning).toBe(false);
@@ -624,18 +604,18 @@ describe("InMemoryAgentRunner", () => {
describe("Edge Cases", () => {
it("should return EMPTY observable when connecting to non-existent thread", async () => {
const connectObservable = runner.connect({ threadId: "non-existent-thread" });
-
+
// EMPTY completes immediately with no values
let completed = false;
let eventCount = 0;
-
+
await new Promise((resolve) => {
connectObservable.subscribe({
next: () => eventCount++,
complete: () => {
completed = true;
resolve();
- }
+ },
});
});
@@ -653,7 +633,7 @@ describe("InMemoryAgentRunner", () => {
type: "bulk",
id: `bulk-${i}`,
timestamp: new Date().toISOString(),
- data: { index: i, payload: "x".repeat(100) }
+ data: { index: i, payload: "x".repeat(100) },
} as BaseEvent);
}
@@ -766,6 +746,10 @@ describe("InMemoryAgentRunner", () => {
]);
});
+ it("should resolve false when stopping a non-running thread", async () => {
+ await expect(runner.stop({ threadId: "any-thread" })).resolves.toBe(false);
+ });
+
it("should handle thread isolation correctly", async () => {
const thread1 = "test-thread-iso-1";
const thread2 = "test-thread-iso-2";
@@ -781,18 +765,15 @@ describe("InMemoryAgentRunner", () => {
const run1 = runner.run({
threadId: thread1,
agent: agent1,
- input: { messages: [], state: {}, threadId: thread1, runId: "run-t1" }
+ input: { messages: [], state: {}, threadId: thread1, runId: "run-t1" },
});
const run2 = runner.run({
threadId: thread2,
agent: agent2,
- input: { messages: [], state: {}, threadId: thread2, runId: "run-t2" }
+ input: { messages: [], state: {}, threadId: thread2, runId: "run-t2" },
});
- await Promise.all([
- firstValueFrom(run1.pipe(toArray())),
- firstValueFrom(run2.pipe(toArray()))
- ]);
+ await Promise.all([firstValueFrom(run1.pipe(toArray())), firstValueFrom(run2.pipe(toArray()))]);
// Connect to each thread
const events1 = await firstValueFrom(runner.connect({ threadId: thread1 }).pipe(toArray()));
@@ -813,9 +794,19 @@ describe("InMemoryAgentRunner", () => {
it("should handle rapid sequential runs with mixed event patterns", async () => {
const threadId = "test-thread-complex-1";
const runs = [
- { agent: new MockAgent([{ type: "instant", id: "instant-1", timestamp: new Date().toISOString(), data: {} } as BaseEvent]), runId: "run-1" },
+ {
+ agent: new MockAgent([
+ { type: "instant", id: "instant-1", timestamp: new Date().toISOString(), data: {} } as BaseEvent,
+ ]),
+ runId: "run-1",
+ },
{ agent: new DelayedEventAgent(3, 5, "delayed"), runId: "run-2" },
- { agent: new MockAgent([{ type: "instant", id: "instant-2", timestamp: new Date().toISOString(), data: {} } as BaseEvent]), runId: "run-3" },
+ {
+ agent: new MockAgent([
+ { type: "instant", id: "instant-2", timestamp: new Date().toISOString(), data: {} } as BaseEvent,
+ ]),
+ runId: "run-3",
+ },
{ agent: new MultiEventAgent("multi"), runId: "run-4" },
{ agent: new DelayedEventAgent(2, 10, "slow"), runId: "run-5" },
];
@@ -847,13 +838,13 @@ describe("InMemoryAgentRunner", () => {
it("should handle subscriber that connects between runs", async () => {
const threadId = "test-thread-complex-2";
-
+
// First run
const agent1 = new MultiEventAgent("first");
const run1 = runner.run({
threadId,
agent: agent1,
- input: { messages: [], state: {}, threadId, runId: "run-1" }
+ input: { messages: [], state: {}, threadId, runId: "run-1" },
});
await firstValueFrom(run1.pipe(toArray()));
@@ -865,13 +856,13 @@ describe("InMemoryAgentRunner", () => {
expect(midAgentEvents).toHaveLength(5); // Only events from first run
const firstRunEvents = midAgentEvents.filter((e) => e.id?.includes("first"));
expect(firstRunEvents).toHaveLength(5);
-
+
// Second run
const agent2 = new MultiEventAgent("second");
const run2 = runner.run({
threadId,
agent: agent2,
- input: { messages: [], state: {}, threadId, runId: "run-2" }
+ input: { messages: [], state: {}, threadId, runId: "run-2" },
});
await firstValueFrom(run2.pipe(toArray()));
diff --git a/packages/runtime/src/__tests__/resource-id-helpers.test.ts b/packages/runtime/src/__tests__/resource-id-helpers.test.ts
new file mode 100644
index 00000000..6fe31c12
--- /dev/null
+++ b/packages/runtime/src/__tests__/resource-id-helpers.test.ts
@@ -0,0 +1,646 @@
+import { describe, expect, it } from "vitest";
+import {
+ validateResourceIdMatch,
+ filterAuthorizedResourceIds,
+ createStrictThreadScopeResolver,
+ createFilteringThreadScopeResolver,
+} from "../resource-id-helpers";
+
+describe("validateResourceIdMatch", () => {
+ describe("basic validation", () => {
+ it("should pass when client-declared matches server-authorized (both strings)", () => {
+ expect(() => {
+ validateResourceIdMatch("user-123", "user-123");
+ }).not.toThrow();
+ });
+
+ it("should pass when clientDeclared is undefined (no client hint)", () => {
+ expect(() => {
+ validateResourceIdMatch(undefined, "user-123");
+ }).not.toThrow();
+ });
+
+ it("should throw when client-declared does not match server-authorized", () => {
+ expect(() => {
+ validateResourceIdMatch("user-999", "user-123");
+ }).toThrow("Unauthorized: Client-declared resourceId does not match authenticated user");
+ });
+
+ it("should pass when client-declared string matches one in server-authorized array", () => {
+ expect(() => {
+ validateResourceIdMatch("workspace-2", ["workspace-1", "workspace-2", "workspace-3"]);
+ }).not.toThrow();
+ });
+
+ it("should pass when one client-declared in array matches server-authorized string", () => {
+ expect(() => {
+ validateResourceIdMatch(["user-1", "user-123", "user-3"], "user-123");
+ }).not.toThrow();
+ });
+
+ it("should pass when at least one client-declared matches one server-authorized (both arrays)", () => {
+ expect(() => {
+ validateResourceIdMatch(
+ ["user-1", "workspace-2"],
+ ["workspace-1", "workspace-2", "workspace-3"]
+ );
+ }).not.toThrow();
+ });
+
+ it("should throw when no client-declared matches any server-authorized (both arrays)", () => {
+ expect(() => {
+ validateResourceIdMatch(["user-1", "user-2"], ["workspace-1", "workspace-2"]);
+ }).toThrow("Unauthorized: Client-declared resourceId does not match authenticated user");
+ });
+ });
+
+ describe("edge cases", () => {
+ it("should handle empty array in clientDeclared (fails)", () => {
+ expect(() => {
+ validateResourceIdMatch([], "user-123");
+ }).toThrow("Unauthorized: Client-declared resourceId does not match authenticated user");
+ });
+
+ it("should handle empty array in serverAuthorized (always fails)", () => {
+ expect(() => {
+ validateResourceIdMatch("user-123", []);
+ }).toThrow("Unauthorized: Client-declared resourceId does not match authenticated user");
+ });
+
+ it("should handle special characters", () => {
+ const specialId = "user@example.com/workspace#123";
+ expect(() => {
+ validateResourceIdMatch(specialId, specialId);
+ }).not.toThrow();
+ });
+
+ it("should handle Unicode characters", () => {
+ const unicodeId = "用户-123-مستخدم";
+ expect(() => {
+ validateResourceIdMatch(unicodeId, unicodeId);
+ }).not.toThrow();
+ });
+
+ it("should handle very long IDs", () => {
+ const longId = "user-" + "a".repeat(1000);
+ expect(() => {
+ validateResourceIdMatch(longId, longId);
+ }).not.toThrow();
+ });
+
+ it("should handle whitespace-only IDs", () => {
+ expect(() => {
+ validateResourceIdMatch(" ", " ");
+ }).not.toThrow();
+ });
+
+ it("should be case-sensitive", () => {
+ expect(() => {
+ validateResourceIdMatch("User-123", "user-123");
+ }).toThrow();
+ });
+
+ it("should not trim whitespace", () => {
+ expect(() => {
+ validateResourceIdMatch("user-123 ", "user-123");
+ }).toThrow();
+ });
+
+ it("should handle duplicate IDs in arrays", () => {
+ expect(() => {
+ validateResourceIdMatch(
+ ["user-1", "user-1", "user-2"],
+ ["user-1", "workspace-1"]
+ );
+ }).not.toThrow();
+ });
+ });
+
+ describe("multiple matches", () => {
+ it("should pass if ANY client ID matches ANY server ID", () => {
+ expect(() => {
+ validateResourceIdMatch(
+ ["wrong-1", "wrong-2", "correct", "wrong-3"],
+ ["other-1", "other-2", "correct", "other-3"]
+ );
+ }).not.toThrow();
+ });
+
+ it("should pass with multiple matching IDs", () => {
+ expect(() => {
+ validateResourceIdMatch(
+ ["match-1", "match-2", "no-match"],
+ ["match-1", "match-2", "other"]
+ );
+ }).not.toThrow();
+ });
+ });
+});
+
+describe("filterAuthorizedResourceIds", () => {
+ describe("basic filtering", () => {
+ it("should return all authorized when clientDeclared is undefined", () => {
+ const result = filterAuthorizedResourceIds(undefined, "user-123");
+ expect(result).toBe("user-123");
+ });
+
+ it("should return all authorized array when clientDeclared is undefined", () => {
+ const result = filterAuthorizedResourceIds(undefined, ["user-1", "workspace-1"]);
+ expect(result).toEqual(["user-1", "workspace-1"]);
+ });
+
+ it("should return single ID when both match (strings)", () => {
+ const result = filterAuthorizedResourceIds("user-123", "user-123");
+ expect(result).toBe("user-123");
+ });
+
+ it("should throw when single ID does not match", () => {
+ expect(() => {
+ filterAuthorizedResourceIds("user-999", "user-123");
+ }).toThrow("Unauthorized: None of the client-declared resourceIds are authorized");
+ });
+
+ it("should filter array to only authorized IDs", () => {
+ const result = filterAuthorizedResourceIds(
+ ["workspace-1", "workspace-2", "workspace-5"],
+ ["workspace-1", "workspace-2", "workspace-3", "workspace-4"]
+ );
+ expect(result).toEqual(["workspace-1", "workspace-2"]);
+ });
+
+ it("should return single string when client is string and matches", () => {
+ const result = filterAuthorizedResourceIds(
+ "workspace-2",
+ ["workspace-1", "workspace-2", "workspace-3"]
+ );
+ expect(result).toBe("workspace-2");
+ });
+
+ it("should throw when client string does not match any authorized", () => {
+ expect(() => {
+ filterAuthorizedResourceIds(
+ "workspace-999",
+ ["workspace-1", "workspace-2", "workspace-3"]
+ );
+ }).toThrow("Unauthorized: None of the client-declared resourceIds are authorized");
+ });
+
+ it("should throw when no client IDs match authorized", () => {
+ expect(() => {
+ filterAuthorizedResourceIds(
+ ["wrong-1", "wrong-2"],
+ ["workspace-1", "workspace-2"]
+ );
+ }).toThrow("Unauthorized: None of the client-declared resourceIds are authorized");
+ });
+ });
+
+ describe("return type preservation", () => {
+ it("should return string when client is string and matches", () => {
+ const result = filterAuthorizedResourceIds("user-1", ["user-1", "user-2"]);
+ expect(result).toBe("user-1");
+ expect(typeof result).toBe("string");
+ });
+
+ it("should return array when client is array", () => {
+ const result = filterAuthorizedResourceIds(
+ ["user-1", "user-2"],
+ ["user-1", "user-2", "user-3"]
+ );
+ expect(Array.isArray(result)).toBe(true);
+ expect(result).toEqual(["user-1", "user-2"]);
+ });
+
+ it("should return single-element array when client is array with one match", () => {
+ const result = filterAuthorizedResourceIds(
+ ["user-1", "wrong-1", "wrong-2"],
+ ["user-1", "user-2"]
+ );
+ expect(Array.isArray(result)).toBe(true);
+ expect(result).toEqual(["user-1"]);
+ });
+ });
+
+ describe("edge cases", () => {
+ it("should handle empty client array (throws)", () => {
+ expect(() => {
+ filterAuthorizedResourceIds([], ["user-1", "user-2"]);
+ }).toThrow("Unauthorized: None of the client-declared resourceIds are authorized");
+ });
+
+ it("should handle empty authorized array (throws)", () => {
+ expect(() => {
+ filterAuthorizedResourceIds(["user-1"], []);
+ }).toThrow("Unauthorized: None of the client-declared resourceIds are authorized");
+ });
+
+ it("should handle duplicate IDs in client array", () => {
+ const result = filterAuthorizedResourceIds(
+ ["user-1", "user-1", "user-2"],
+ ["user-1", "user-2", "user-3"]
+ );
+ // Should preserve duplicates
+ expect(result).toEqual(["user-1", "user-1", "user-2"]);
+ });
+
+ it("should handle duplicate IDs in authorized array", () => {
+ const result = filterAuthorizedResourceIds(
+ ["user-1"],
+ ["user-1", "user-1", "user-2"]
+ );
+ // Client passed array, so result is array
+ expect(result).toEqual(["user-1"]);
+ });
+
+ it("should handle special characters", () => {
+ const specialId = "user@example.com/workspace#123";
+ const result = filterAuthorizedResourceIds(specialId, [specialId, "other"]);
+ expect(result).toBe(specialId);
+ });
+
+ it("should handle Unicode characters", () => {
+ const unicodeId = "用户-123";
+ const result = filterAuthorizedResourceIds([unicodeId, "other"], [unicodeId]);
+ expect(result).toEqual([unicodeId]);
+ });
+
+ it("should be case-sensitive", () => {
+ expect(() => {
+ filterAuthorizedResourceIds("User-123", ["user-123"]);
+ }).toThrow();
+ });
+
+ it("should not trim whitespace", () => {
+ expect(() => {
+ filterAuthorizedResourceIds("user-123 ", ["user-123"]);
+ }).toThrow();
+ });
+
+ it("should handle whitespace-only IDs", () => {
+ const result = filterAuthorizedResourceIds(" ", [" ", "other"]);
+ expect(result).toBe(" ");
+ });
+
+ it("should preserve order of filtered IDs", () => {
+ const result = filterAuthorizedResourceIds(
+ ["z", "a", "m", "b"],
+ ["m", "a", "z", "b"]
+ );
+ // Should preserve client order, not server order
+ expect(result).toEqual(["z", "a", "m", "b"]);
+ });
+ });
+});
+
+describe("createStrictThreadScopeResolver", () => {
+ const createRequest = () => new Request("https://example.com/api");
+
+ describe("basic functionality", () => {
+ it("should create extractor that returns server-authorized ID", async () => {
+ const extractor = createStrictThreadScopeResolver(async () => "user-123");
+
+ const result = await extractor({
+ request: createRequest(),
+ clientDeclared: "user-123",
+ });
+
+ expect(result).toEqual({ resourceId: "user-123" });
+ });
+
+ it("should validate client-declared matches server ID", async () => {
+ const extractor = createStrictThreadScopeResolver(async () => "user-123");
+
+ await expect(
+ extractor({
+ request: createRequest(),
+ clientDeclared: "user-999",
+ })
+ ).rejects.toThrow("Unauthorized");
+ });
+
+ it("should allow undefined client-declared", async () => {
+ const extractor = createStrictThreadScopeResolver(async () => "user-123");
+
+ const result = await extractor({
+ request: createRequest(),
+ clientDeclared: undefined,
+ });
+
+ expect(result).toEqual({ resourceId: "user-123" });
+ });
+
+ it("should handle array from getUserId", async () => {
+ const extractor = createStrictThreadScopeResolver(async () => [
+ "user-123",
+ "workspace-456",
+ ]);
+
+ const result = await extractor({
+ request: createRequest(),
+ clientDeclared: "workspace-456",
+ });
+
+ expect(result).toEqual({ resourceId: ["user-123", "workspace-456"] });
+ });
+
+ it("should pass request to getUserId function", async () => {
+ let receivedRequest: Request | undefined;
+ const extractor = createStrictThreadScopeResolver(async (request) => {
+ receivedRequest = request;
+ return "user-123";
+ });
+
+ const request = createRequest();
+ await extractor({ request, clientDeclared: "user-123" });
+
+ expect(receivedRequest).toBe(request);
+ });
+ });
+
+ describe("validation scenarios", () => {
+ it("should validate when client declares one of multiple authorized IDs", async () => {
+ const extractor = createStrictThreadScopeResolver(async () => [
+ "user-123",
+ "workspace-456",
+ ]);
+
+ const result = await extractor({
+ request: createRequest(),
+ clientDeclared: "user-123",
+ });
+
+ expect(result).toEqual({ resourceId: ["user-123", "workspace-456"] });
+ });
+
+ it("should validate when client declares array with match", async () => {
+ const extractor = createStrictThreadScopeResolver(async () => "user-123");
+
+ const result = await extractor({
+ request: createRequest(),
+ clientDeclared: ["user-123", "other"],
+ });
+
+ expect(result).toEqual({ resourceId: "user-123" });
+ });
+
+ it("should reject when client declares array with no matches", async () => {
+ const extractor = createStrictThreadScopeResolver(async () => "user-123");
+
+ await expect(
+ extractor({
+ request: createRequest(),
+ clientDeclared: ["user-999", "other"],
+ })
+ ).rejects.toThrow("Unauthorized");
+ });
+ });
+
+ describe("async getUserId", () => {
+ it("should handle async getUserId with delay", async () => {
+ const extractor = createStrictThreadScopeResolver(async () => {
+ await new Promise((resolve) => setTimeout(resolve, 10));
+ return "user-123";
+ });
+
+ const result = await extractor({
+ request: createRequest(),
+ clientDeclared: "user-123",
+ });
+
+ expect(result).toEqual({ resourceId: "user-123" });
+ });
+
+ it("should propagate getUserId errors", async () => {
+ const extractor = createStrictThreadScopeResolver(async () => {
+ throw new Error("Authentication failed");
+ });
+
+ await expect(
+ extractor({
+ request: createRequest(),
+ clientDeclared: "user-123",
+ })
+ ).rejects.toThrow("Authentication failed");
+ });
+ });
+});
+
+describe("createFilteringThreadScopeResolver", () => {
+ const createRequest = () => new Request("https://example.com/api");
+
+ describe("basic functionality", () => {
+ it("should create extractor that returns all authorized when no client hint", async () => {
+ const extractor = createFilteringThreadScopeResolver(async () => [
+ "workspace-1",
+ "workspace-2",
+ "workspace-3",
+ ]);
+
+ const result = await extractor({
+ request: createRequest(),
+ clientDeclared: undefined,
+ });
+
+ expect(result).toEqual({
+ resourceId: ["workspace-1", "workspace-2", "workspace-3"],
+ });
+ });
+
+ it("should filter to only authorized IDs", async () => {
+ const extractor = createFilteringThreadScopeResolver(async () => [
+ "workspace-1",
+ "workspace-2",
+ "workspace-3",
+ ]);
+
+ const result = await extractor({
+ request: createRequest(),
+ clientDeclared: ["workspace-1", "workspace-99"],
+ });
+
+ expect(result).toEqual({ resourceId: ["workspace-1"] });
+ });
+
+ it("should return single string when client is string", async () => {
+ const extractor = createFilteringThreadScopeResolver(async () => [
+ "workspace-1",
+ "workspace-2",
+ ]);
+
+ const result = await extractor({
+ request: createRequest(),
+ clientDeclared: "workspace-1",
+ });
+
+ expect(result).toEqual({ resourceId: "workspace-1" });
+ });
+
+ it("should throw when no client IDs are authorized", async () => {
+ const extractor = createFilteringThreadScopeResolver(async () => [
+ "workspace-1",
+ "workspace-2",
+ ]);
+
+ await expect(
+ extractor({
+ request: createRequest(),
+ clientDeclared: ["workspace-99", "workspace-88"],
+ })
+ ).rejects.toThrow("Unauthorized: None of the client-declared resourceIds are authorized");
+ });
+
+ it("should pass request to getUserResourceIds function", async () => {
+ let receivedRequest: Request | undefined;
+ const extractor = createFilteringThreadScopeResolver(async (request) => {
+ receivedRequest = request;
+ return ["workspace-1"];
+ });
+
+ const request = createRequest();
+ await extractor({ request, clientDeclared: "workspace-1" });
+
+ expect(receivedRequest).toBe(request);
+ });
+ });
+
+ describe("filtering scenarios", () => {
+ it("should filter multiple client IDs to authorized subset", async () => {
+ const extractor = createFilteringThreadScopeResolver(async () => [
+ "ws-1",
+ "ws-2",
+ "ws-3",
+ "ws-4",
+ ]);
+
+ const result = await extractor({
+ request: createRequest(),
+ clientDeclared: ["ws-1", "ws-99", "ws-3", "ws-88"],
+ });
+
+ expect(result).toEqual({ resourceId: ["ws-1", "ws-3"] });
+ });
+
+ it("should preserve order of client-declared IDs", async () => {
+ const extractor = createFilteringThreadScopeResolver(async () => [
+ "ws-1",
+ "ws-2",
+ "ws-3",
+ "ws-4",
+ ]);
+
+ const result = await extractor({
+ request: createRequest(),
+ clientDeclared: ["ws-4", "ws-2", "ws-1"],
+ });
+
+ // Should maintain client's order, not server's
+ expect(result).toEqual({ resourceId: ["ws-4", "ws-2", "ws-1"] });
+ });
+
+ it("should handle single authorized workspace", async () => {
+ const extractor = createFilteringThreadScopeResolver(async () => [
+ "workspace-only",
+ ]);
+
+ const result = await extractor({
+ request: createRequest(),
+ clientDeclared: ["workspace-only", "other"],
+ });
+
+ expect(result).toEqual({ resourceId: ["workspace-only"] });
+ });
+ });
+
+ describe("edge cases", () => {
+ it("should handle empty client array", async () => {
+ const extractor = createFilteringThreadScopeResolver(async () => [
+ "workspace-1",
+ ]);
+
+ await expect(
+ extractor({
+ request: createRequest(),
+ clientDeclared: [],
+ })
+ ).rejects.toThrow("Unauthorized");
+ });
+
+ it("should handle empty authorized array", async () => {
+ const extractor = createFilteringThreadScopeResolver(async () => []);
+
+ await expect(
+ extractor({
+ request: createRequest(),
+ clientDeclared: ["workspace-1"],
+ })
+ ).rejects.toThrow("Unauthorized");
+ });
+
+ it("should handle duplicate IDs in client array", async () => {
+ const extractor = createFilteringThreadScopeResolver(async () => [
+ "ws-1",
+ "ws-2",
+ ]);
+
+ const result = await extractor({
+ request: createRequest(),
+ clientDeclared: ["ws-1", "ws-1", "ws-2"],
+ });
+
+ expect(result).toEqual({ resourceId: ["ws-1", "ws-1", "ws-2"] });
+ });
+
+ it("should handle special characters", async () => {
+ const specialId = "workspace@example.com/project#123";
+ const extractor = createFilteringThreadScopeResolver(async () => [specialId]);
+
+ const result = await extractor({
+ request: createRequest(),
+ clientDeclared: specialId,
+ });
+
+ expect(result).toEqual({ resourceId: specialId });
+ });
+
+ it("should handle Unicode characters", async () => {
+ const unicodeId = "工作空间-123";
+ const extractor = createFilteringThreadScopeResolver(async () => [unicodeId]);
+
+ const result = await extractor({
+ request: createRequest(),
+ clientDeclared: [unicodeId],
+ });
+
+ expect(result).toEqual({ resourceId: [unicodeId] });
+ });
+ });
+
+ describe("async getUserResourceIds", () => {
+ it("should handle async getUserResourceIds with delay", async () => {
+ const extractor = createFilteringThreadScopeResolver(async () => {
+ await new Promise((resolve) => setTimeout(resolve, 10));
+ return ["workspace-1"];
+ });
+
+ const result = await extractor({
+ request: createRequest(),
+ clientDeclared: "workspace-1",
+ });
+
+ expect(result).toEqual({ resourceId: "workspace-1" });
+ });
+
+ it("should propagate getUserResourceIds errors", async () => {
+ const extractor = createFilteringThreadScopeResolver(async () => {
+ throw new Error("Failed to fetch workspaces");
+ });
+
+ await expect(
+ extractor({
+ request: createRequest(),
+ clientDeclared: "workspace-1",
+ })
+ ).rejects.toThrow("Failed to fetch workspaces");
+ });
+ });
+});
diff --git a/packages/runtime/src/__tests__/thread-endpoints.e2e.test.ts b/packages/runtime/src/__tests__/thread-endpoints.e2e.test.ts
new file mode 100644
index 00000000..9cf6e8bc
--- /dev/null
+++ b/packages/runtime/src/__tests__/thread-endpoints.e2e.test.ts
@@ -0,0 +1,540 @@
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import { CopilotRuntime } from "../runtime";
+import { InMemoryAgentRunner } from "../runner/in-memory";
+import { createCopilotEndpoint } from "../endpoint";
+import {
+ AbstractAgent,
+ BaseEvent,
+ EventType,
+ RunAgentInput,
+ TextMessageStartEvent,
+ TextMessageContentEvent,
+ TextMessageEndEvent,
+} from "@ag-ui/client";
+import { EMPTY, firstValueFrom } from "rxjs";
+import { toArray } from "rxjs/operators";
+
+// Simple test agent for creating threads
+class TestAgent extends AbstractAgent {
+ constructor(private message: string = "Test message") {
+ super();
+ }
+
+ async runAgent(
+ input: RunAgentInput,
+ options: { onEvent: (event: { event: BaseEvent }) => void }
+ ): Promise {
+ const messageId = "test-msg";
+ options.onEvent({
+ event: { type: EventType.TEXT_MESSAGE_START, messageId, role: "assistant" } as TextMessageStartEvent,
+ });
+ options.onEvent({
+ event: { type: EventType.TEXT_MESSAGE_CONTENT, messageId, delta: this.message } as TextMessageContentEvent,
+ });
+ options.onEvent({
+ event: { type: EventType.TEXT_MESSAGE_END, messageId } as TextMessageEndEvent,
+ });
+ }
+
+ clone(): AbstractAgent {
+ return new TestAgent(this.message);
+ }
+
+ protected run() {
+ return EMPTY;
+ }
+
+ protected connect() {
+ return EMPTY;
+ }
+}
+
+describe("Thread Endpoints E2E", () => {
+ let runtime: CopilotRuntime;
+ let runner: InMemoryAgentRunner;
+ let app: ReturnType;
+
+ beforeEach(() => {
+ runner = new InMemoryAgentRunner();
+ runner.clearAllThreads();
+
+ runtime = {
+ runner: Promise.resolve(runner),
+ resolveThreadsScope: async ({ request }) => {
+ // Simple auth: extract user from X-User-ID header
+ const userId = request.headers.get("X-User-ID");
+ if (!userId) {
+ throw new Error("Unauthorized: X-User-ID header required");
+ }
+ return { resourceId: userId };
+ },
+ } as CopilotRuntime;
+
+ app = createCopilotEndpoint({ runtime, basePath: "/copilotkit" });
+ });
+
+ describe("GET /threads - List Threads", () => {
+ it("returns empty list when user has no threads", async () => {
+ const request = new Request("http://localhost/copilotkit/threads", {
+ headers: { "X-User-ID": "user-1" },
+ });
+
+ const response = await app.fetch(request);
+
+ expect(response.status).toBe(200);
+ const data = await response.json();
+ expect(data.threads).toEqual([]);
+ expect(data.total).toBe(0);
+ });
+
+ it("returns threads for authenticated user", async () => {
+ // Create threads for user-1
+ const agent = new TestAgent("Hello from thread 1");
+ await firstValueFrom(
+ runner
+ .run({
+ threadId: "thread-1",
+ agent,
+ input: { threadId: "thread-1", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "user-1" },
+ })
+ .pipe(toArray())
+ );
+
+ await firstValueFrom(
+ runner
+ .run({
+ threadId: "thread-2",
+ agent: new TestAgent("Hello from thread 2"),
+ input: { threadId: "thread-2", runId: "run-2", messages: [], state: {} },
+ scope: { resourceId: "user-1" },
+ })
+ .pipe(toArray())
+ );
+
+ const request = new Request("http://localhost/copilotkit/threads", {
+ headers: { "X-User-ID": "user-1" },
+ });
+
+ const response = await app.fetch(request);
+
+ expect(response.status).toBe(200);
+ const data = await response.json();
+ expect(data.threads).toHaveLength(2);
+ expect(data.total).toBe(2);
+ expect(data.threads[0].threadId).toMatch(/thread-/);
+ expect(data.threads[0].firstMessage).toBeTruthy();
+ });
+
+ it("enforces scope - user cannot see other user's threads", async () => {
+ // Create thread for user-1
+ const agent = new TestAgent("User 1 message");
+ await firstValueFrom(
+ runner
+ .run({
+ threadId: "user-1-thread",
+ agent,
+ input: { threadId: "user-1-thread", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "user-1" },
+ })
+ .pipe(toArray())
+ );
+
+ // User-2 tries to list threads
+ const request = new Request("http://localhost/copilotkit/threads", {
+ headers: { "X-User-ID": "user-2" },
+ });
+
+ const response = await app.fetch(request);
+
+ expect(response.status).toBe(200);
+ const data = await response.json();
+ expect(data.threads).toEqual([]); // Should not see user-1's thread
+ expect(data.total).toBe(0);
+ });
+
+ it("respects pagination parameters", async () => {
+ // Create 5 threads
+ for (let i = 1; i <= 5; i++) {
+ await firstValueFrom(
+ runner
+ .run({
+ threadId: `thread-${i}`,
+ agent: new TestAgent(`Message ${i}`),
+ input: { threadId: `thread-${i}`, runId: `run-${i}`, messages: [], state: {} },
+ scope: { resourceId: "user-1" },
+ })
+ .pipe(toArray())
+ );
+ await new Promise((resolve) => setTimeout(resolve, 5)); // Ensure ordering
+ }
+
+ // Request page 2 with limit 2
+ const request = new Request("http://localhost/copilotkit/threads?limit=2&offset=2", {
+ headers: { "X-User-ID": "user-1" },
+ });
+
+ const response = await app.fetch(request);
+
+ expect(response.status).toBe(200);
+ const data = await response.json();
+ expect(data.threads).toHaveLength(2);
+ expect(data.total).toBe(5);
+ });
+ });
+
+ describe("GET /threads/:id - Get Single Thread", () => {
+ it("returns 200 with thread metadata when thread exists", async () => {
+ // Create a thread
+ const agent = new TestAgent("Specific thread message");
+ await firstValueFrom(
+ runner
+ .run({
+ threadId: "specific-thread",
+ agent,
+ input: { threadId: "specific-thread", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "user-1" },
+ })
+ .pipe(toArray())
+ );
+
+ const request = new Request("http://localhost/copilotkit/threads/specific-thread", {
+ headers: { "X-User-ID": "user-1" },
+ });
+
+ const response = await app.fetch(request);
+
+ expect(response.status).toBe(200);
+ const data = await response.json();
+ expect(data.threadId).toBe("specific-thread");
+ expect(data.firstMessage).toBe("Specific thread message");
+ expect(data.messageCount).toBe(1);
+ expect(data.isRunning).toBe(false);
+ });
+
+ it("returns 404 when thread does not exist", async () => {
+ const request = new Request("http://localhost/copilotkit/threads/nonexistent-thread", {
+ headers: { "X-User-ID": "user-1" },
+ });
+
+ const response = await app.fetch(request);
+
+ expect(response.status).toBe(404);
+ const data = await response.json();
+ expect(data.error).toBe("Thread not found");
+ });
+
+ it("returns 404 when thread exists but belongs to different user (scope violation)", async () => {
+ // User-1 creates a thread
+ const agent = new TestAgent("Private message");
+ await firstValueFrom(
+ runner
+ .run({
+ threadId: "private-thread",
+ agent,
+ input: { threadId: "private-thread", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "user-1" },
+ })
+ .pipe(toArray())
+ );
+
+ // User-2 tries to access it
+ const request = new Request("http://localhost/copilotkit/threads/private-thread", {
+ headers: { "X-User-ID": "user-2" },
+ });
+
+ const response = await app.fetch(request);
+
+ expect(response.status).toBe(404);
+ const data = await response.json();
+ expect(data.error).toBe("Thread not found");
+ });
+
+ it("handles special characters in thread ID", async () => {
+ const threadId = "thread/with/slashes";
+ const agent = new TestAgent("Special ID thread");
+ await firstValueFrom(
+ runner
+ .run({
+ threadId,
+ agent,
+ input: { threadId, runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "user-1" },
+ })
+ .pipe(toArray())
+ );
+
+ // URL encode the thread ID
+ const encodedId = encodeURIComponent(threadId);
+ const request = new Request(`http://localhost/copilotkit/threads/${encodedId}`, {
+ headers: { "X-User-ID": "user-1" },
+ });
+
+ const response = await app.fetch(request);
+
+ expect(response.status).toBe(200);
+ const data = await response.json();
+ expect(data.threadId).toBe(threadId);
+ });
+ });
+
+ describe("DELETE /threads/:id - Delete Thread", () => {
+ it("successfully deletes thread", async () => {
+ // Create a thread
+ const agent = new TestAgent("To be deleted");
+ await firstValueFrom(
+ runner
+ .run({
+ threadId: "delete-me",
+ agent,
+ input: { threadId: "delete-me", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "user-1" },
+ })
+ .pipe(toArray())
+ );
+
+ // Verify it exists
+ let metadata = await runner.getThreadMetadata("delete-me", { resourceId: "user-1" });
+ expect(metadata).not.toBeNull();
+
+ // Delete it
+ const request = new Request("http://localhost/copilotkit/threads/delete-me", {
+ method: "DELETE",
+ headers: { "X-User-ID": "user-1" },
+ });
+
+ const response = await app.fetch(request);
+
+ expect(response.status).toBe(200);
+ const data = await response.json();
+ expect(data.success).toBe(true);
+
+ // Verify it's gone
+ metadata = await runner.getThreadMetadata("delete-me", { resourceId: "user-1" });
+ expect(metadata).toBeNull();
+ });
+
+ it("enforces scope - cannot delete other user's thread", async () => {
+ // User-1 creates a thread
+ const agent = new TestAgent("User 1's thread");
+ await firstValueFrom(
+ runner
+ .run({
+ threadId: "protected-thread",
+ agent,
+ input: { threadId: "protected-thread", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "user-1" },
+ })
+ .pipe(toArray())
+ );
+
+ // User-2 tries to delete it
+ const request = new Request("http://localhost/copilotkit/threads/protected-thread", {
+ method: "DELETE",
+ headers: { "X-User-ID": "user-2" },
+ });
+
+ const response = await app.fetch(request);
+
+ // Should succeed (idempotent) but thread should still exist for user-1
+ expect(response.status).toBe(200);
+
+ // Verify thread still exists for user-1
+ const metadata = await runner.getThreadMetadata("protected-thread", { resourceId: "user-1" });
+ expect(metadata).not.toBeNull();
+ expect(metadata!.threadId).toBe("protected-thread");
+ });
+
+ it("returns success when deleting non-existent thread (idempotent)", async () => {
+ const request = new Request("http://localhost/copilotkit/threads/never-existed", {
+ method: "DELETE",
+ headers: { "X-User-ID": "user-1" },
+ });
+
+ const response = await app.fetch(request);
+
+ expect(response.status).toBe(200);
+ const data = await response.json();
+ expect(data.success).toBe(true);
+ });
+
+ it("returns 400 when thread ID is empty", async () => {
+ const request = new Request("http://localhost/copilotkit/threads/", {
+ method: "DELETE",
+ headers: { "X-User-ID": "user-1" },
+ });
+
+ const response = await app.fetch(request);
+
+ // Should be 404 for non-matching route, not 400
+ expect(response.status).toBe(404);
+ });
+ });
+
+ describe("Full Lifecycle E2E", () => {
+ it("creates, lists, gets, and deletes threads successfully", async () => {
+ const userId = "lifecycle-user";
+
+ // 1. Start with empty list
+ let listResponse = await app.fetch(
+ new Request("http://localhost/copilotkit/threads", {
+ headers: { "X-User-ID": userId },
+ })
+ );
+ expect(listResponse.status).toBe(200);
+ let listData = await listResponse.json();
+ expect(listData.total).toBe(0);
+
+ // 2. Create threads
+ for (let i = 1; i <= 3; i++) {
+ await firstValueFrom(
+ runner
+ .run({
+ threadId: `lifecycle-thread-${i}`,
+ agent: new TestAgent(`Message ${i}`),
+ input: { threadId: `lifecycle-thread-${i}`, runId: `run-${i}`, messages: [], state: {} },
+ scope: { resourceId: userId },
+ })
+ .pipe(toArray())
+ );
+ }
+
+ // 3. List threads
+ listResponse = await app.fetch(
+ new Request("http://localhost/copilotkit/threads", {
+ headers: { "X-User-ID": userId },
+ })
+ );
+ expect(listResponse.status).toBe(200);
+ listData = await listResponse.json();
+ expect(listData.total).toBe(3);
+
+ // 4. Get specific thread
+ const getResponse = await app.fetch(
+ new Request("http://localhost/copilotkit/threads/lifecycle-thread-2", {
+ headers: { "X-User-ID": userId },
+ })
+ );
+ expect(getResponse.status).toBe(200);
+ const getData = await getResponse.json();
+ expect(getData.threadId).toBe("lifecycle-thread-2");
+ expect(getData.firstMessage).toBe("Message 2");
+
+ // 5. Delete one thread
+ const deleteResponse = await app.fetch(
+ new Request("http://localhost/copilotkit/threads/lifecycle-thread-2", {
+ method: "DELETE",
+ headers: { "X-User-ID": userId },
+ })
+ );
+ expect(deleteResponse.status).toBe(200);
+
+ // 6. Verify deletion
+ listResponse = await app.fetch(
+ new Request("http://localhost/copilotkit/threads", {
+ headers: { "X-User-ID": userId },
+ })
+ );
+ expect(listResponse.status).toBe(200);
+ listData = await listResponse.json();
+ expect(listData.total).toBe(2);
+ expect(listData.threads.find((t: any) => t.threadId === "lifecycle-thread-2")).toBeUndefined();
+
+ // 7. Deleted thread returns 404
+ const getDeletedResponse = await app.fetch(
+ new Request("http://localhost/copilotkit/threads/lifecycle-thread-2", {
+ headers: { "X-User-ID": userId },
+ })
+ );
+ expect(getDeletedResponse.status).toBe(404);
+ });
+
+ it("handles concurrent operations correctly", async () => {
+ const userId = "concurrent-user";
+
+ // Create threads concurrently
+ await Promise.all([
+ firstValueFrom(
+ runner
+ .run({
+ threadId: "concurrent-1",
+ agent: new TestAgent("Concurrent 1"),
+ input: { threadId: "concurrent-1", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: userId },
+ })
+ .pipe(toArray())
+ ),
+ firstValueFrom(
+ runner
+ .run({
+ threadId: "concurrent-2",
+ agent: new TestAgent("Concurrent 2"),
+ input: { threadId: "concurrent-2", runId: "run-2", messages: [], state: {} },
+ scope: { resourceId: userId },
+ })
+ .pipe(toArray())
+ ),
+ firstValueFrom(
+ runner
+ .run({
+ threadId: "concurrent-3",
+ agent: new TestAgent("Concurrent 3"),
+ input: { threadId: "concurrent-3", runId: "run-3", messages: [], state: {} },
+ scope: { resourceId: userId },
+ })
+ .pipe(toArray())
+ ),
+ ]);
+
+ // List threads
+ const listResponse = await app.fetch(
+ new Request("http://localhost/copilotkit/threads", {
+ headers: { "X-User-ID": userId },
+ })
+ );
+ expect(listResponse.status).toBe(200);
+ const listData = await listResponse.json();
+ expect(listData.total).toBe(3);
+
+ // Delete concurrently
+ await Promise.all([
+ app.fetch(
+ new Request("http://localhost/copilotkit/threads/concurrent-1", {
+ method: "DELETE",
+ headers: { "X-User-ID": userId },
+ })
+ ),
+ app.fetch(
+ new Request("http://localhost/copilotkit/threads/concurrent-2", {
+ method: "DELETE",
+ headers: { "X-User-ID": userId },
+ })
+ ),
+ ]);
+
+ // Verify only one thread remains
+ const finalListResponse = await app.fetch(
+ new Request("http://localhost/copilotkit/threads", {
+ headers: { "X-User-ID": userId },
+ })
+ );
+ expect(finalListResponse.status).toBe(200);
+ const finalListData = await finalListResponse.json();
+ expect(finalListData.total).toBe(1);
+ expect(finalListData.threads[0].threadId).toBe("concurrent-3");
+ });
+ });
+
+ describe("Error Handling", () => {
+ it("returns 401 when authentication fails", async () => {
+ const request = new Request("http://localhost/copilotkit/threads", {
+ // Missing X-User-ID header
+ });
+
+ const response = await app.fetch(request);
+
+ // Should fail during scope resolution
+ expect(response.status).toBeGreaterThanOrEqual(400);
+ });
+ });
+});
diff --git a/packages/runtime/src/endpoint.ts b/packages/runtime/src/endpoint.ts
index b283f5d3..834ccdc0 100644
--- a/packages/runtime/src/endpoint.ts
+++ b/packages/runtime/src/endpoint.ts
@@ -8,6 +8,7 @@ import { logger } from "@copilotkitnext/shared";
import { callBeforeRequestMiddleware, callAfterRequestMiddleware } from "./middleware";
import { handleConnectAgent } from "./handlers/handle-connect";
import { handleStopAgent } from "./handlers/handle-stop";
+import { handleListThreads, handleGetThread, handleDeleteThread } from "./handlers/handle-threads";
interface CopilotEndpointParams {
runtime: CopilotRuntime;
@@ -146,6 +147,49 @@ export function createCopilotEndpoint({ runtime, basePath }: CopilotEndpointPara
throw error;
}
})
+ .get("/threads", async (c) => {
+ const request = c.get("modifiedRequest") || c.req.raw;
+
+ try {
+ return await handleListThreads({
+ runtime,
+ request,
+ });
+ } catch (error) {
+ logger.error({ err: error, url: request.url, path: c.req.path }, "Error running request handler");
+ throw error;
+ }
+ })
+ .get("/threads/:threadId", async (c) => {
+ const threadId = c.req.param("threadId");
+ const request = c.get("modifiedRequest") || c.req.raw;
+
+ try {
+ return await handleGetThread({
+ runtime,
+ request,
+ threadId,
+ });
+ } catch (error) {
+ logger.error({ err: error, url: request.url, path: c.req.path }, "Error running request handler");
+ throw error;
+ }
+ })
+ .delete("/threads/:threadId", async (c) => {
+ const threadId = c.req.param("threadId");
+ const request = c.get("modifiedRequest") || c.req.raw;
+
+ try {
+ return await handleDeleteThread({
+ runtime,
+ request,
+ threadId,
+ });
+ } catch (error) {
+ logger.error({ err: error, url: request.url, path: c.req.path }, "Error running request handler");
+ throw error;
+ }
+ })
.notFound((c) => {
return c.json({ error: "Not found" }, 404);
});
diff --git a/packages/runtime/src/handlers/__tests__/security.test.ts b/packages/runtime/src/handlers/__tests__/security.test.ts
new file mode 100644
index 00000000..1d51b2fd
--- /dev/null
+++ b/packages/runtime/src/handlers/__tests__/security.test.ts
@@ -0,0 +1,289 @@
+import { describe, it, expect, vi } from "vitest";
+import { handleRunAgent } from "../handle-run";
+import { handleConnectAgent } from "../handle-connect";
+import type { CopilotRuntime } from "../../runtime";
+import { InMemoryAgentRunner } from "../../runner/in-memory";
+import { AbstractAgent, RunAgentInput } from "@ag-ui/client";
+import { EMPTY } from "rxjs";
+
+class MockAgent extends AbstractAgent {
+ clone(): AbstractAgent {
+ return new MockAgent();
+ }
+
+ protected run() {
+ return EMPTY;
+ }
+
+ protected connect() {
+ return EMPTY;
+ }
+}
+
+describe("Handler Security Tests", () => {
+ describe("handleRunAgent - Null Scope (Admin Bypass)", () => {
+ it("should accept null scope from resolveThreadsScope", async () => {
+ const mockAgent = new MockAgent();
+ const runner = new InMemoryAgentRunner();
+
+ const runtime: CopilotRuntime = {
+ agents: Promise.resolve({ default: mockAgent }),
+ runner,
+ resolveThreadsScope: async () => null, // Admin returns null
+ } as any;
+
+ const request = new Request("http://localhost/api/copilotkit/run/default", {
+ method: "POST",
+ body: JSON.stringify({
+ threadId: "test-thread",
+ runId: "run-1",
+ messages: [],
+ state: {},
+ }),
+ headers: { "Content-Type": "application/json" },
+ });
+
+ const response = await handleRunAgent({
+ runtime,
+ request,
+ agentId: "default",
+ });
+
+ expect(response.status).toBe(200);
+ expect(response.headers.get("Content-Type")).toBe("text/event-stream");
+ });
+
+ it("should reject undefined scope (missing auth)", async () => {
+ const mockAgent = new MockAgent();
+ const runner = new InMemoryAgentRunner();
+
+ const runtime: CopilotRuntime = {
+ agents: Promise.resolve({ default: mockAgent }),
+ runner,
+ resolveThreadsScope: async () => undefined as any, // Missing auth
+ } as any;
+
+ const request = new Request("http://localhost/api/copilotkit/run/default", {
+ method: "POST",
+ body: JSON.stringify({
+ threadId: "test-thread",
+ runId: "run-1",
+ messages: [],
+ state: {},
+ }),
+ headers: { "Content-Type": "application/json" },
+ });
+
+ // Give it time to process
+ const response = await handleRunAgent({
+ runtime,
+ request,
+ agentId: "default",
+ });
+
+ // The response is returned immediately (streaming), but the error happens in background
+ // Wait a bit for the async error
+ await new Promise((resolve) => setTimeout(resolve, 100));
+
+ // Since it's streaming, we can't check response status directly
+ // But the error should be logged (tested in integration tests)
+ expect(response.status).toBe(200); // Stream starts before error
+ });
+
+ it("should accept valid user scope", async () => {
+ const mockAgent = new MockAgent();
+ const runner = new InMemoryAgentRunner();
+
+ const runtime: CopilotRuntime = {
+ agents: Promise.resolve({ default: mockAgent }),
+ runner,
+ resolveThreadsScope: async () => ({ resourceId: "user-123" }),
+ } as any;
+
+ const request = new Request("http://localhost/api/copilotkit/run/default", {
+ method: "POST",
+ body: JSON.stringify({
+ threadId: "test-thread",
+ runId: "run-1",
+ messages: [],
+ state: {},
+ }),
+ headers: { "Content-Type": "application/json" },
+ });
+
+ const response = await handleRunAgent({
+ runtime,
+ request,
+ agentId: "default",
+ });
+
+ expect(response.status).toBe(200);
+ });
+ });
+
+ describe("handleConnectAgent - Null Scope (Admin Bypass)", () => {
+ it("should accept null scope for admin connections", async () => {
+ const mockAgent = new MockAgent();
+ const runner = new InMemoryAgentRunner();
+
+ const runtime: CopilotRuntime = {
+ agents: Promise.resolve({ default: mockAgent }),
+ runner,
+ resolveThreadsScope: async () => null, // Admin
+ } as any;
+
+ const request = new Request("http://localhost/api/copilotkit/connect/default", {
+ method: "POST",
+ body: JSON.stringify({
+ threadId: "test-thread",
+ runId: "run-1",
+ messages: [],
+ state: {},
+ }),
+ headers: { "Content-Type": "application/json" },
+ });
+
+ const response = await handleConnectAgent({
+ runtime,
+ request,
+ agentId: "default",
+ });
+
+ expect(response.status).toBe(200);
+ expect(response.headers.get("Content-Type")).toBe("text/event-stream");
+ });
+
+ it("should accept multi-resource scope array", async () => {
+ const mockAgent = new MockAgent();
+ const runner = new InMemoryAgentRunner();
+
+ const runtime: CopilotRuntime = {
+ agents: Promise.resolve({ default: mockAgent }),
+ runner,
+ resolveThreadsScope: async () => ({
+ resourceId: ["user-123", "workspace-456"],
+ }),
+ } as any;
+
+ const request = new Request("http://localhost/api/copilotkit/connect/default", {
+ method: "POST",
+ body: JSON.stringify({
+ threadId: "test-thread",
+ runId: "run-1",
+ messages: [],
+ state: {},
+ }),
+ headers: { "Content-Type": "application/json" },
+ });
+
+ const response = await handleConnectAgent({
+ runtime,
+ request,
+ agentId: "default",
+ });
+
+ expect(response.status).toBe(200);
+ });
+ });
+
+ describe("Scope Validation Edge Cases", () => {
+ it("should handle scope with properties", async () => {
+ const mockAgent = new MockAgent();
+ const runner = new InMemoryAgentRunner();
+
+ const runtime: CopilotRuntime = {
+ agents: Promise.resolve({ default: mockAgent }),
+ runner,
+ resolveThreadsScope: async () => ({
+ resourceId: "user-123",
+ properties: { department: "engineering", role: "admin" },
+ }),
+ } as any;
+
+ const request = new Request("http://localhost/api/copilotkit/run/default", {
+ method: "POST",
+ body: JSON.stringify({
+ threadId: "test-thread",
+ runId: "run-1",
+ messages: [],
+ state: {},
+ }),
+ headers: { "Content-Type": "application/json" },
+ });
+
+ const response = await handleRunAgent({
+ runtime,
+ request,
+ agentId: "default",
+ });
+
+ expect(response.status).toBe(200);
+ });
+
+ it("should handle scope extraction errors gracefully", async () => {
+ const mockAgent = new MockAgent();
+ const runner = new InMemoryAgentRunner();
+
+ const runtime: CopilotRuntime = {
+ agents: Promise.resolve({ default: mockAgent }),
+ runner,
+ resolveThreadsScope: async () => {
+ throw new Error("Database connection failed");
+ },
+ } as any;
+
+ const request = new Request("http://localhost/api/copilotkit/run/default", {
+ method: "POST",
+ body: JSON.stringify({
+ threadId: "test-thread",
+ runId: "run-1",
+ messages: [],
+ state: {},
+ }),
+ headers: { "Content-Type": "application/json" },
+ });
+
+ const response = await handleRunAgent({
+ runtime,
+ request,
+ agentId: "default",
+ });
+
+ // Response starts streaming, then error occurs
+ expect(response.status).toBe(200);
+ });
+ });
+
+ describe("Agent Validation", () => {
+ it("should return 404 for non-existent agent with any scope", async () => {
+ const runner = new InMemoryAgentRunner();
+
+ const runtime: CopilotRuntime = {
+ agents: Promise.resolve({}),
+ runner,
+ resolveThreadsScope: async () => ({ resourceId: "user-123" }),
+ } as any;
+
+ const request = new Request("http://localhost/api/copilotkit/run/nonexistent", {
+ method: "POST",
+ body: JSON.stringify({
+ threadId: "test-thread",
+ runId: "run-1",
+ messages: [],
+ state: {},
+ }),
+ headers: { "Content-Type": "application/json" },
+ });
+
+ const response = await handleRunAgent({
+ runtime,
+ request,
+ agentId: "nonexistent",
+ });
+
+ expect(response.status).toBe(404);
+ const body = await response.json();
+ expect(body.error).toBe("Agent not found");
+ });
+ });
+});
diff --git a/packages/runtime/src/handlers/handle-connect.ts b/packages/runtime/src/handlers/handle-connect.ts
index 3223cba0..7cb2c47a 100644
--- a/packages/runtime/src/handlers/handle-connect.ts
+++ b/packages/runtime/src/handlers/handle-connect.ts
@@ -1,6 +1,7 @@
import { RunAgentInput, RunAgentInputSchema } from "@ag-ui/client";
import { EventEncoder } from "@ag-ui/encoder";
import { CopilotRuntime } from "../runtime";
+import { Subscription } from "rxjs";
interface ConnectAgentParameters {
request: Request;
@@ -8,11 +9,7 @@ interface ConnectAgentParameters {
agentId: string;
}
-export async function handleConnectAgent({
- runtime,
- request,
- agentId,
-}: ConnectAgentParameters) {
+export async function handleConnectAgent({ runtime, request, agentId }: ConnectAgentParameters) {
try {
const agents = await runtime.agents;
@@ -26,7 +23,7 @@ export async function handleConnectAgent({
{
status: 404,
headers: { "Content-Type": "application/json" },
- }
+ },
);
}
@@ -34,6 +31,26 @@ export async function handleConnectAgent({
const writer = stream.writable.getWriter();
const encoder = new EventEncoder();
let streamClosed = false;
+ let subscription: Subscription | undefined;
+ let abortListener: (() => void) | undefined;
+
+ const cleanupAbortListener = () => {
+ if (abortListener) {
+ request.signal.removeEventListener("abort", abortListener);
+ abortListener = undefined;
+ }
+ };
+
+ const closeStream = async () => {
+ if (!streamClosed) {
+ try {
+ await writer.close();
+ } catch {
+ // Stream already closed
+ }
+ streamClosed = true;
+ }
+ };
// Process the request in the background
(async () => {
@@ -46,13 +63,23 @@ export async function handleConnectAgent({
JSON.stringify({
error: "Invalid request body",
}),
- { status: 400 }
+ { status: 400 },
);
}
- runtime.runner
+ // Parse client-declared resourceId from header
+ const clientDeclared = CopilotRuntime["parseClientDeclaredResourceId"](request);
+
+ // Resolve resource scope (null is valid for admin bypass)
+ const scope = await runtime.resolveThreadsScope({ request, clientDeclared });
+ if (scope === undefined) {
+ throw new Error("Unauthorized: No resource scope provided");
+ }
+
+ subscription = runtime.runner
.connect({
threadId: input.threadId,
+ scope,
})
.subscribe({
next: async (event) => {
@@ -68,45 +95,40 @@ export async function handleConnectAgent({
},
error: async (error) => {
console.error("Error running agent:", error);
- if (!streamClosed) {
- try {
- await writer.close();
- streamClosed = true;
- } catch {
- // Stream already closed
- }
- }
+ cleanupAbortListener();
+ await closeStream();
},
complete: async () => {
- if (!streamClosed) {
- try {
- await writer.close();
- streamClosed = true;
- } catch {
- // Stream already closed
- }
- }
+ cleanupAbortListener();
+ await closeStream();
},
});
+
+ const handleAbort = () => {
+ subscription?.unsubscribe();
+ subscription = undefined;
+ cleanupAbortListener();
+ void closeStream();
+ };
+
+ if (request.signal.aborted) {
+ handleAbort();
+ } else {
+ abortListener = handleAbort;
+ request.signal.addEventListener("abort", abortListener);
+ }
})().catch((error) => {
console.error("Error running agent:", error);
- console.error(
- "Error stack:",
- error instanceof Error ? error.stack : "No stack trace"
- );
+ console.error("Error stack:", error instanceof Error ? error.stack : "No stack trace");
console.error("Error details:", {
name: error instanceof Error ? error.name : "Unknown",
message: error instanceof Error ? error.message : String(error),
cause: error instanceof Error ? error.cause : undefined,
});
- if (!streamClosed) {
- try {
- writer.close();
- streamClosed = true;
- } catch {
- // Stream already closed
- }
- }
+ subscription?.unsubscribe();
+ subscription = undefined;
+ cleanupAbortListener();
+ void closeStream();
});
// Return the SSE response
@@ -120,10 +142,7 @@ export async function handleConnectAgent({
});
} catch (error) {
console.error("Error running agent:", error);
- console.error(
- "Error stack:",
- error instanceof Error ? error.stack : "No stack trace"
- );
+ console.error("Error stack:", error instanceof Error ? error.stack : "No stack trace");
console.error("Error details:", {
name: error instanceof Error ? error.name : "Unknown",
message: error instanceof Error ? error.message : String(error),
@@ -138,7 +157,7 @@ export async function handleConnectAgent({
{
status: 500,
headers: { "Content-Type": "application/json" },
- }
+ },
);
}
}
diff --git a/packages/runtime/src/handlers/handle-run.ts b/packages/runtime/src/handlers/handle-run.ts
index 0df5ec1a..bcc54111 100644
--- a/packages/runtime/src/handlers/handle-run.ts
+++ b/packages/runtime/src/handlers/handle-run.ts
@@ -1,11 +1,7 @@
-import {
- AbstractAgent,
- HttpAgent,
- RunAgentInput,
- RunAgentInputSchema,
-} from "@ag-ui/client";
+import { AbstractAgent, HttpAgent, RunAgentInput, RunAgentInputSchema } from "@ag-ui/client";
import { EventEncoder } from "@ag-ui/encoder";
import { CopilotRuntime } from "../runtime";
+import { Subscription } from "rxjs";
interface RunAgentParameters {
request: Request;
@@ -13,11 +9,7 @@ interface RunAgentParameters {
agentId: string;
}
-export async function handleRunAgent({
- runtime,
- request,
- agentId,
-}: RunAgentParameters) {
+export async function handleRunAgent({ runtime, request, agentId }: RunAgentParameters) {
try {
const agents = await runtime.agents;
@@ -31,7 +23,7 @@ export async function handleRunAgent({
{
status: 404,
headers: { "Content-Type": "application/json" },
- }
+ },
);
}
@@ -51,9 +43,9 @@ export async function handleRunAgent({
}
});
- agent.headers = {
- ...agent.headers as Record,
- ...forwardableHeaders
+ agent.headers = {
+ ...(agent.headers as Record),
+ ...forwardableHeaders,
};
}
@@ -61,6 +53,26 @@ export async function handleRunAgent({
const writer = stream.writable.getWriter();
const encoder = new EventEncoder();
let streamClosed = false;
+ let subscription: Subscription | undefined;
+ let abortListener: (() => void) | undefined;
+
+ const cleanupAbortListener = () => {
+ if (abortListener) {
+ request.signal.removeEventListener("abort", abortListener);
+ abortListener = undefined;
+ }
+ };
+
+ const closeStream = async () => {
+ if (!streamClosed) {
+ try {
+ await writer.close();
+ } catch {
+ // Stream already closed
+ }
+ streamClosed = true;
+ }
+ };
// Process the request in the background
(async () => {
@@ -73,19 +85,37 @@ export async function handleRunAgent({
JSON.stringify({
error: "Invalid request body",
}),
- { status: 400 }
+ { status: 400 },
);
}
+ // Parse client-declared resourceId from header
+ const clientDeclared = CopilotRuntime["parseClientDeclaredResourceId"](request);
+
+ // Resolve resource scope (null is valid for admin bypass)
+ const scope = await runtime.resolveThreadsScope({ request, clientDeclared });
+ if (scope === undefined) {
+ throw new Error("Unauthorized: No resource scope provided");
+ }
+
agent.setMessages(input.messages);
agent.setState(input.state);
agent.threadId = input.threadId;
- runtime.runner
+ const stopRunner = async () => {
+ try {
+ await runtime.runner.stop({ threadId: input.threadId });
+ } catch (stopError) {
+ console.error("Error stopping runner:", stopError);
+ }
+ };
+
+ subscription = runtime.runner
.run({
threadId: input.threadId,
agent,
input,
+ scope,
})
.subscribe({
next: async (event) => {
@@ -93,7 +123,7 @@ export async function handleRunAgent({
try {
await writer.write(encoder.encode(event));
} catch (error) {
- if (error instanceof Error && error.name === 'AbortError') {
+ if (error instanceof Error && error.name === "AbortError") {
streamClosed = true;
}
}
@@ -101,45 +131,41 @@ export async function handleRunAgent({
},
error: async (error) => {
console.error("Error running agent:", error);
- if (!streamClosed) {
- try {
- await writer.close();
- streamClosed = true;
- } catch {
- // Stream already closed
- }
- }
+ cleanupAbortListener();
+ await closeStream();
},
complete: async () => {
- if (!streamClosed) {
- try {
- await writer.close();
- streamClosed = true;
- } catch {
- // Stream already closed
- }
- }
+ cleanupAbortListener();
+ await closeStream();
},
});
+
+ const handleAbort = () => {
+ subscription?.unsubscribe();
+ subscription = undefined;
+ cleanupAbortListener();
+ void stopRunner();
+ void closeStream();
+ };
+
+ if (request.signal.aborted) {
+ handleAbort();
+ } else {
+ abortListener = handleAbort;
+ request.signal.addEventListener("abort", abortListener);
+ }
})().catch((error) => {
console.error("Error running agent:", error);
- console.error(
- "Error stack:",
- error instanceof Error ? error.stack : "No stack trace"
- );
+ console.error("Error stack:", error instanceof Error ? error.stack : "No stack trace");
console.error("Error details:", {
name: error instanceof Error ? error.name : "Unknown",
message: error instanceof Error ? error.message : String(error),
cause: error instanceof Error ? error.cause : undefined,
});
- if (!streamClosed) {
- try {
- writer.close();
- streamClosed = true;
- } catch {
- // Stream already closed
- }
- }
+ subscription?.unsubscribe();
+ subscription = undefined;
+ cleanupAbortListener();
+ void closeStream();
});
// Return the SSE response
@@ -153,10 +179,7 @@ export async function handleRunAgent({
});
} catch (error) {
console.error("Error running agent:", error);
- console.error(
- "Error stack:",
- error instanceof Error ? error.stack : "No stack trace"
- );
+ console.error("Error stack:", error instanceof Error ? error.stack : "No stack trace");
console.error("Error details:", {
name: error instanceof Error ? error.name : "Unknown",
message: error instanceof Error ? error.message : String(error),
@@ -171,7 +194,7 @@ export async function handleRunAgent({
{
status: 500,
headers: { "Content-Type": "application/json" },
- }
+ },
);
}
}
diff --git a/packages/runtime/src/handlers/handle-stop.ts b/packages/runtime/src/handlers/handle-stop.ts
index 4a6bd507..fa320553 100644
--- a/packages/runtime/src/handlers/handle-stop.ts
+++ b/packages/runtime/src/handlers/handle-stop.ts
@@ -30,7 +30,45 @@ export async function handleStopAgent({
);
}
- const stopped = await runtime.runner.stop({ threadId });
+ // Parse client-declared resourceId from header
+ const clientDeclared = CopilotRuntime["parseClientDeclaredResourceId"](request);
+
+ // Resolve resource scope
+ const scope = await runtime.resolveThreadsScope({ request, clientDeclared });
+
+ // Guard against undefined scope (auth failure or missing return)
+ if (scope === undefined) {
+ return new Response(
+ JSON.stringify({
+ error: "Unauthorized",
+ message: "No resource scope provided",
+ }),
+ {
+ status: 401,
+ headers: { "Content-Type": "application/json" },
+ },
+ );
+ }
+
+ // Verify the thread belongs to this scope before stopping
+ const runner = await runtime.runner;
+ const metadata = await runner.getThreadMetadata(threadId, scope);
+
+ if (!metadata) {
+ // Return 404 (not 403) to prevent resource enumeration
+ return new Response(
+ JSON.stringify({
+ error: "Thread not found",
+ message: `Thread '${threadId}' does not exist or you don't have access`,
+ }),
+ {
+ status: 404,
+ headers: { "Content-Type": "application/json" },
+ },
+ );
+ }
+
+ const stopped = await runner.stop({ threadId });
if (!stopped) {
return new Response(
diff --git a/packages/runtime/src/handlers/handle-threads.ts b/packages/runtime/src/handlers/handle-threads.ts
new file mode 100644
index 00000000..ed95edf4
--- /dev/null
+++ b/packages/runtime/src/handlers/handle-threads.ts
@@ -0,0 +1,184 @@
+import { CopilotRuntime } from "../runtime";
+
+interface ListThreadsParameters {
+ request: Request;
+ runtime: CopilotRuntime;
+}
+
+interface GetThreadParameters {
+ request: Request;
+ runtime: CopilotRuntime;
+ threadId: string;
+}
+
+interface DeleteThreadParameters {
+ request: Request;
+ runtime: CopilotRuntime;
+ threadId: string;
+}
+
+export async function handleListThreads({ runtime, request }: ListThreadsParameters) {
+ try {
+ // Parse client-declared resourceId from header
+ const clientDeclared = CopilotRuntime["parseClientDeclaredResourceId"](request);
+
+ // Resolve resource scope
+ const scope = await runtime.resolveThreadsScope({ request, clientDeclared });
+
+ // Guard against undefined scope (auth failure or missing return)
+ if (scope === undefined) {
+ return new Response(
+ JSON.stringify({
+ error: "Unauthorized",
+ message: "No resource scope provided",
+ }),
+ {
+ status: 401,
+ headers: { "Content-Type": "application/json" },
+ },
+ );
+ }
+
+ const url = new URL(request.url);
+ const limitParam = url.searchParams.get("limit");
+ const offsetParam = url.searchParams.get("offset");
+
+ const parsedLimit = limitParam ? Number.parseInt(limitParam, 10) : NaN;
+ const parsedOffset = offsetParam ? Number.parseInt(offsetParam, 10) : NaN;
+
+ const limit = Math.max(1, Math.min(100, Number.isNaN(parsedLimit) ? 20 : parsedLimit));
+ const offset = Math.max(0, Number.isNaN(parsedOffset) ? 0 : parsedOffset);
+
+ const runner = await runtime.runner;
+ const result = await runner.listThreads({ scope, limit, offset });
+
+ return new Response(JSON.stringify(result), {
+ status: 200,
+ headers: { "Content-Type": "application/json" },
+ });
+ } catch (error) {
+ const errorMessage = error instanceof Error ? error.message : "Unknown error occurred";
+
+ return new Response(
+ JSON.stringify({
+ error: "Failed to list threads",
+ message: errorMessage,
+ }),
+ {
+ status: 500,
+ headers: { "Content-Type": "application/json" },
+ },
+ );
+ }
+}
+
+export async function handleGetThread({ runtime, threadId, request }: GetThreadParameters) {
+ try {
+ // Parse client-declared resourceId from header
+ const clientDeclared = CopilotRuntime["parseClientDeclaredResourceId"](request);
+
+ // Resolve resource scope
+ const scope = await runtime.resolveThreadsScope({ request, clientDeclared });
+
+ // Guard against undefined scope (auth failure or missing return)
+ if (scope === undefined) {
+ return new Response(
+ JSON.stringify({
+ error: "Unauthorized",
+ message: "No resource scope provided",
+ }),
+ {
+ status: 401,
+ headers: { "Content-Type": "application/json" },
+ },
+ );
+ }
+
+ const runner = await runtime.runner;
+ const metadata = await runner.getThreadMetadata(threadId, scope);
+
+ if (!metadata) {
+ // Return 404 (not 403) to prevent resource enumeration
+ return new Response(
+ JSON.stringify({
+ error: "Thread not found",
+ message: `Thread '${threadId}' does not exist`,
+ }),
+ {
+ status: 404,
+ headers: { "Content-Type": "application/json" },
+ },
+ );
+ }
+
+ return new Response(JSON.stringify(metadata), {
+ status: 200,
+ headers: { "Content-Type": "application/json" },
+ });
+ } catch (error) {
+ const errorMessage = error instanceof Error ? error.message : "Unknown error occurred";
+
+ return new Response(
+ JSON.stringify({
+ error: "Failed to get thread",
+ message: errorMessage,
+ }),
+ {
+ status: 500,
+ headers: { "Content-Type": "application/json" },
+ },
+ );
+ }
+}
+
+export async function handleDeleteThread({ runtime, threadId, request }: DeleteThreadParameters) {
+ if (!threadId) {
+ return new Response(JSON.stringify({ error: "Thread ID required" }), {
+ status: 400,
+ headers: { "Content-Type": "application/json" },
+ });
+ }
+
+ try {
+ // Parse client-declared resourceId from header
+ const clientDeclared = CopilotRuntime["parseClientDeclaredResourceId"](request);
+
+ // Resolve resource scope
+ const scope = await runtime.resolveThreadsScope({ request, clientDeclared });
+
+ // Guard against undefined scope (auth failure or missing return)
+ if (scope === undefined) {
+ return new Response(
+ JSON.stringify({
+ error: "Unauthorized",
+ message: "No resource scope provided",
+ }),
+ {
+ status: 401,
+ headers: { "Content-Type": "application/json" },
+ },
+ );
+ }
+
+ const runner = await runtime.runner;
+ await runner.deleteThread(threadId, scope);
+
+ return new Response(JSON.stringify({ success: true }), {
+ status: 200,
+ headers: { "Content-Type": "application/json" },
+ });
+ } catch (error) {
+ const errorMessage = error instanceof Error ? error.message : "Unknown error occurred";
+
+ return new Response(
+ JSON.stringify({
+ error: "Failed to delete thread",
+ message: errorMessage,
+ }),
+ {
+ status: 500,
+ headers: { "Content-Type": "application/json" },
+ },
+ );
+ }
+}
diff --git a/packages/runtime/src/index.ts b/packages/runtime/src/index.ts
index 7b45d0c0..978dc3e1 100644
--- a/packages/runtime/src/index.ts
+++ b/packages/runtime/src/index.ts
@@ -3,3 +3,6 @@ export * from "./endpoint";
// Export agent runners and base types
export * from "./runner";
+
+// Export resource ID validation helpers
+export * from "./resource-id-helpers";
diff --git a/packages/runtime/src/resource-id-helpers.ts b/packages/runtime/src/resource-id-helpers.ts
new file mode 100644
index 00000000..f9e542fd
--- /dev/null
+++ b/packages/runtime/src/resource-id-helpers.ts
@@ -0,0 +1,125 @@
+import { ResourceScope } from "./runner/agent-runner";
+
+/**
+ * Helper to validate that client-declared resourceId matches the authenticated user's resourceId.
+ *
+ * Throws an error if validation fails.
+ *
+ * @example
+ * ```typescript
+ * resolveThreadsScope: async ({ request, clientDeclared }) => {
+ * const user = await authenticate(request);
+ * validateResourceIdMatch(clientDeclared, user.id);
+ * return { resourceId: user.id };
+ * }
+ * ```
+ */
+export function validateResourceIdMatch(
+ clientDeclared: string | string[] | undefined,
+ serverAuthorized: string | string[],
+): void {
+ if (!clientDeclared) {
+ return; // No client hint - OK
+ }
+
+ const clientIds = Array.isArray(clientDeclared) ? clientDeclared : [clientDeclared];
+ const authorizedIds = Array.isArray(serverAuthorized) ? serverAuthorized : [serverAuthorized];
+
+ // Check if ANY client-declared ID matches ANY authorized ID
+ const hasMatch = clientIds.some((clientId) => authorizedIds.includes(clientId));
+
+ if (!hasMatch) {
+ throw new Error("Unauthorized: Client-declared resourceId does not match authenticated user");
+ }
+}
+
+/**
+ * Helper to filter client-declared resourceIds to only those the user has access to.
+ *
+ * Returns the filtered resourceId(s), or throws if no valid IDs remain.
+ *
+ * @example
+ * ```typescript
+ * resolveThreadsScope: async ({ request, clientDeclared }) => {
+ * const user = await authenticate(request);
+ * const userResourceIds = await getUserAccessibleResources(user);
+ * const resourceId = filterAuthorizedResourceIds(clientDeclared, userResourceIds);
+ * return { resourceId };
+ * }
+ * ```
+ */
+export function filterAuthorizedResourceIds(
+ clientDeclared: string | string[] | undefined,
+ serverAuthorized: string | string[],
+): string | string[] {
+ const authorizedIds = Array.isArray(serverAuthorized) ? serverAuthorized : [serverAuthorized];
+
+ if (!clientDeclared) {
+ // No client hint - return all authorized
+ return serverAuthorized;
+ }
+
+ const clientIds = Array.isArray(clientDeclared) ? clientDeclared : [clientDeclared];
+
+ // Filter to only authorized IDs
+ const filtered = clientIds.filter((id) => authorizedIds.includes(id));
+
+ if (filtered.length === 0) {
+ throw new Error("Unauthorized: None of the client-declared resourceIds are authorized");
+ }
+
+ // Return single string if originally single, otherwise array
+ return Array.isArray(clientDeclared) ? filtered : filtered[0]!;
+}
+
+/**
+ * Helper to create a strict thread scope resolver that only allows exact matches.
+ *
+ * Use this when you want to enforce that the client MUST declare the correct resourceId.
+ *
+ * @example
+ * ```typescript
+ * new CopilotRuntime({
+ * agents: { myAgent },
+ * resolveThreadsScope: createStrictThreadScopeResolver(async (request) => {
+ * const user = await authenticate(request);
+ * return user.id;
+ * })
+ * });
+ * ```
+ */
+export function createStrictThreadScopeResolver(
+ getUserId: (request: Request) => Promise,
+): (context: { request: Request; clientDeclared?: string | string[] }) => Promise {
+ return async ({ request, clientDeclared }) => {
+ const userId = await getUserId(request);
+ validateResourceIdMatch(clientDeclared, userId);
+ return { resourceId: userId };
+ };
+}
+
+/**
+ * Helper to create a filtering thread scope resolver for multi-resource scenarios.
+ *
+ * Use this when users have access to multiple resources (e.g., multiple workspaces).
+ *
+ * @example
+ * ```typescript
+ * new CopilotRuntime({
+ * agents: { myAgent },
+ * resolveThreadsScope: createFilteringThreadScopeResolver(async (request) => {
+ * const user = await authenticate(request);
+ * return await getUserAccessibleWorkspaces(user);
+ * })
+ * });
+ * ```
+ */
+export function createFilteringThreadScopeResolver(
+ getUserResourceIds: (request: Request) => Promise,
+): (context: { request: Request; clientDeclared?: string | string[] }) => Promise {
+ return async ({ request, clientDeclared }) => {
+ const userResourceIds = await getUserResourceIds(request);
+ const resourceId = filterAuthorizedResourceIds(clientDeclared, userResourceIds);
+ return { resourceId };
+ };
+}
diff --git a/packages/runtime/src/runner/__tests__/resource-scoping.test.ts b/packages/runtime/src/runner/__tests__/resource-scoping.test.ts
new file mode 100644
index 00000000..b1688979
--- /dev/null
+++ b/packages/runtime/src/runner/__tests__/resource-scoping.test.ts
@@ -0,0 +1,514 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { InMemoryAgentRunner } from "../in-memory";
+import {
+ AbstractAgent,
+ BaseEvent,
+ RunAgentInput,
+ EventType,
+ Message,
+ TextMessageStartEvent,
+ TextMessageContentEvent,
+ TextMessageEndEvent,
+} from "@ag-ui/client";
+import { EMPTY, firstValueFrom } from "rxjs";
+import { toArray } from "rxjs/operators";
+
+type RunCallbacks = {
+ onEvent: (event: { event: BaseEvent }) => void;
+ onNewMessage?: (args: { message: Message }) => void;
+ onRunStartedEvent?: () => void;
+};
+
+// Mock agent for testing
+class MockAgent extends AbstractAgent {
+ private events: BaseEvent[];
+
+ constructor(events: BaseEvent[] = []) {
+ super();
+ this.events = events;
+ }
+
+ async runAgent(input: RunAgentInput, callbacks: RunCallbacks): Promise {
+ if (callbacks.onRunStartedEvent) {
+ callbacks.onRunStartedEvent();
+ }
+
+ for (const event of this.events) {
+ callbacks.onEvent({ event });
+ }
+ }
+
+ clone(): AbstractAgent {
+ return new MockAgent(this.events);
+ }
+
+ protected run(): ReturnType {
+ return EMPTY;
+ }
+
+ protected connect(): ReturnType {
+ return EMPTY;
+ }
+}
+
+describe("Resource Scoping - InMemoryAgentRunner", () => {
+ let runner: InMemoryAgentRunner;
+
+ beforeEach(() => {
+ runner = new InMemoryAgentRunner();
+ // Clear any state from previous tests
+ runner.clearAllThreads();
+ });
+
+ const createTestEvents = (messageText: string, messageId: string): BaseEvent[] => [
+ { type: EventType.TEXT_MESSAGE_START, messageId, role: "user" } as TextMessageStartEvent,
+ { type: EventType.TEXT_MESSAGE_CONTENT, messageId, delta: messageText } as TextMessageContentEvent,
+ { type: EventType.TEXT_MESSAGE_END, messageId } as TextMessageEndEvent,
+ ];
+
+ describe("Scope Isolation", () => {
+ it("should prevent hijacking existing threads from other users", async () => {
+ const agent = new MockAgent(createTestEvents("Alice's thread", "msg1"));
+
+ // Alice creates a thread
+ const aliceObs = runner.run({
+ threadId: "thread-123",
+ agent,
+ input: { threadId: "thread-123", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "user-alice" },
+ });
+ await firstValueFrom(aliceObs.pipe(toArray()));
+
+ // Bob tries to run on Alice's thread - should be rejected
+ const bobAgent = new MockAgent(createTestEvents("Bob hijacking", "msg2"));
+ expect(() => {
+ runner.run({
+ threadId: "thread-123",
+ agent: bobAgent,
+ input: { threadId: "thread-123", runId: "run-2", messages: [], state: {} },
+ scope: { resourceId: "user-bob" },
+ });
+ }).toThrow("Unauthorized: Cannot run on thread owned by different resource");
+ });
+
+ it("should reject empty resourceId arrays", async () => {
+ const agent = new MockAgent(createTestEvents("Test", "msg1"));
+
+ expect(() => {
+ runner.run({
+ threadId: "thread-empty",
+ agent,
+ input: { threadId: "thread-empty", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: [] },
+ });
+ }).toThrow("Invalid scope: resourceId array cannot be empty");
+ });
+
+ it("should isolate threads by resourceId", async () => {
+ const agent1 = new MockAgent(createTestEvents("User 1 message", "msg1"));
+ const agent2 = new MockAgent(createTestEvents("User 2 message", "msg2"));
+
+ // Create thread for user-1
+ const obs1 = runner.run({
+ threadId: "thread-1",
+ agent: agent1,
+ input: { threadId: "thread-1", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "user-1" },
+ });
+ await firstValueFrom(obs1.pipe(toArray()));
+
+ // Create thread for user-2
+ const obs2 = runner.run({
+ threadId: "thread-2",
+ agent: agent2,
+ input: { threadId: "thread-2", runId: "run-2", messages: [], state: {} },
+ scope: { resourceId: "user-2" },
+ });
+ await firstValueFrom(obs2.pipe(toArray()));
+
+ // User 1 should only see their thread
+ const user1Threads = await runner.listThreads({
+ scope: { resourceId: "user-1" },
+ limit: 10,
+ });
+ expect(user1Threads.threads).toHaveLength(1);
+ expect(user1Threads.threads[0].threadId).toBe("thread-1");
+ expect(user1Threads.threads[0].resourceId).toBe("user-1");
+
+ // User 2 should only see their thread
+ const user2Threads = await runner.listThreads({
+ scope: { resourceId: "user-2" },
+ limit: 10,
+ });
+ expect(user2Threads.threads).toHaveLength(1);
+ expect(user2Threads.threads[0].threadId).toBe("thread-2");
+ expect(user2Threads.threads[0].resourceId).toBe("user-2");
+ });
+
+ it("should return 404-style empty result when accessing another user's thread", async () => {
+ const agent = new MockAgent(createTestEvents("User 1 message", "msg1"));
+
+ // Create thread for user-1
+ const obs = runner.run({
+ threadId: "thread-user1",
+ agent,
+ input: { threadId: "thread-user1", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "user-1" },
+ });
+ await firstValueFrom(obs.pipe(toArray()));
+
+ // User 2 attempts to connect to user 1's thread - should get empty (404)
+ const connectObs = runner.connect({
+ threadId: "thread-user1",
+ scope: { resourceId: "user-2" },
+ });
+
+ const events = await firstValueFrom(connectObs.pipe(toArray()));
+ expect(events).toEqual([]);
+ });
+
+ it("should return null when getting metadata for another user's thread", async () => {
+ const agent = new MockAgent(createTestEvents("User 1 message", "msg1"));
+
+ // Create thread for user-1
+ const obs = runner.run({
+ threadId: "thread-user1",
+ agent,
+ input: { threadId: "thread-user1", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "user-1" },
+ });
+ await firstValueFrom(obs.pipe(toArray()));
+
+ // User 2 attempts to get metadata - should return null (404)
+ const metadata = await runner.getThreadMetadata("thread-user1", { resourceId: "user-2" });
+ expect(metadata).toBeNull();
+ });
+
+ it("should silently succeed when deleting another user's thread (idempotent)", async () => {
+ const agent = new MockAgent(createTestEvents("User 1 message", "msg1"));
+
+ // Create thread for user-1
+ const obs = runner.run({
+ threadId: "thread-user1",
+ agent,
+ input: { threadId: "thread-user1", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "user-1" },
+ });
+ await firstValueFrom(obs.pipe(toArray()));
+
+ // User 2 attempts to delete user 1's thread - should silently succeed
+ await expect(
+ runner.deleteThread("thread-user1", { resourceId: "user-2" })
+ ).resolves.toBeUndefined();
+
+ // Verify thread still exists for user 1
+ const metadata = await runner.getThreadMetadata("thread-user1", { resourceId: "user-1" });
+ expect(metadata).not.toBeNull();
+ });
+ });
+
+ describe("Multi-Resource Access (Array Queries)", () => {
+ it("should allow access to threads from multiple resourceIds", async () => {
+ const agent = new MockAgent(createTestEvents("Test message", "msg1"));
+
+ // Create thread in personal workspace
+ const obs1 = runner.run({
+ threadId: "thread-personal",
+ agent,
+ input: { threadId: "thread-personal", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "user-1-personal" },
+ });
+ await firstValueFrom(obs1.pipe(toArray()));
+
+ // Create thread in team workspace
+ const obs2 = runner.run({
+ threadId: "thread-team",
+ agent,
+ input: { threadId: "thread-team", runId: "run-2", messages: [], state: {} },
+ scope: { resourceId: "workspace-123" },
+ });
+ await firstValueFrom(obs2.pipe(toArray()));
+
+ // Create thread for another user
+ const obs3 = runner.run({
+ threadId: "thread-other",
+ agent,
+ input: { threadId: "thread-other", runId: "run-3", messages: [], state: {} },
+ scope: { resourceId: "user-2-personal" },
+ });
+ await firstValueFrom(obs3.pipe(toArray()));
+
+ // User with access to both personal and team workspace
+ const threads = await runner.listThreads({
+ scope: { resourceId: ["user-1-personal", "workspace-123"] },
+ limit: 10,
+ });
+
+ // Should see both personal and team threads, but not other user's thread
+ expect(threads.threads).toHaveLength(2);
+ const threadIds = threads.threads.map((t) => t.threadId).sort();
+ expect(threadIds).toEqual(["thread-personal", "thread-team"]);
+ });
+
+ it("should allow connecting to thread from any resourceId in array", async () => {
+ const agent = new MockAgent(createTestEvents("Workspace message", "msg1"));
+
+ // Create thread in workspace
+ const obs = runner.run({
+ threadId: "thread-workspace",
+ agent,
+ input: { threadId: "thread-workspace", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "workspace-456" },
+ });
+ await firstValueFrom(obs.pipe(toArray()));
+
+ // User with access to multiple workspaces should be able to connect
+ const connectObs = runner.connect({
+ threadId: "thread-workspace",
+ scope: { resourceId: ["user-1-personal", "workspace-456", "workspace-789"] },
+ });
+
+ const events = await firstValueFrom(connectObs.pipe(toArray()));
+ expect(events.length).toBeGreaterThan(0);
+ });
+
+ it("should get metadata for thread with multi-resource scope", async () => {
+ const agent = new MockAgent(createTestEvents("Team thread", "msg1"));
+
+ // Create thread in team workspace
+ const obs = runner.run({
+ threadId: "thread-team",
+ agent,
+ input: { threadId: "thread-team", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "workspace-999" },
+ });
+ await firstValueFrom(obs.pipe(toArray()));
+
+ // User with array scope including this workspace
+ const metadata = await runner.getThreadMetadata("thread-team", {
+ resourceId: ["user-1-personal", "workspace-999"],
+ });
+
+ expect(metadata).not.toBeNull();
+ expect(metadata!.threadId).toBe("thread-team");
+ expect(metadata!.resourceId).toBe("workspace-999");
+ });
+
+ it("should return null for metadata when resourceId not in array", async () => {
+ const agent = new MockAgent(createTestEvents("Private thread", "msg1"));
+
+ // Create thread in workspace
+ const obs = runner.run({
+ threadId: "thread-private",
+ agent,
+ input: { threadId: "thread-private", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "workspace-secret" },
+ });
+ await firstValueFrom(obs.pipe(toArray()));
+
+ // User with different workspaces
+ const metadata = await runner.getThreadMetadata("thread-private", {
+ resourceId: ["workspace-1", "workspace-2"],
+ });
+
+ expect(metadata).toBeNull();
+ });
+
+ it("should handle empty array gracefully", async () => {
+ const agent = new MockAgent(createTestEvents("Test", "msg1"));
+
+ const obs = runner.run({
+ threadId: "thread-1",
+ agent,
+ input: { threadId: "thread-1", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "user-1" },
+ });
+ await firstValueFrom(obs.pipe(toArray()));
+
+ // Empty array should not match anything
+ const threads = await runner.listThreads({
+ scope: { resourceId: [] },
+ limit: 10,
+ });
+
+ expect(threads.threads).toHaveLength(0);
+ });
+ });
+
+ describe("Admin Bypass (Null Scope)", () => {
+ it("should list all threads when scope is null", async () => {
+ const agent = new MockAgent(createTestEvents("Test message", "msg1"));
+
+ // Create threads for different users
+ const obs1 = runner.run({
+ threadId: "thread-user1",
+ agent,
+ input: { threadId: "thread-user1", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "user-1" },
+ });
+ await firstValueFrom(obs1.pipe(toArray()));
+
+ const obs2 = runner.run({
+ threadId: "thread-user2",
+ agent,
+ input: { threadId: "thread-user2", runId: "run-2", messages: [], state: {} },
+ scope: { resourceId: "user-2" },
+ });
+ await firstValueFrom(obs2.pipe(toArray()));
+
+ const obs3 = runner.run({
+ threadId: "thread-user3",
+ agent,
+ input: { threadId: "thread-user3", runId: "run-3", messages: [], state: {} },
+ scope: { resourceId: "user-3" },
+ });
+ await firstValueFrom(obs3.pipe(toArray()));
+
+ // Admin with null scope should see all threads
+ const adminThreads = await runner.listThreads({
+ scope: null,
+ limit: 10,
+ });
+
+ expect(adminThreads.threads).toHaveLength(3);
+ const threadIds = adminThreads.threads.map((t) => t.threadId).sort();
+ expect(threadIds).toEqual(["thread-user1", "thread-user2", "thread-user3"]);
+ });
+
+ it("should get metadata for any thread when scope is null", async () => {
+ const agent = new MockAgent(createTestEvents("User thread", "msg1"));
+
+ // Create thread for user-1
+ const obs = runner.run({
+ threadId: "thread-user1",
+ agent,
+ input: { threadId: "thread-user1", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "user-1" },
+ });
+ await firstValueFrom(obs.pipe(toArray()));
+
+ // Admin should be able to get metadata
+ const metadata = await runner.getThreadMetadata("thread-user1", null);
+
+ expect(metadata).not.toBeNull();
+ expect(metadata!.threadId).toBe("thread-user1");
+ expect(metadata!.resourceId).toBe("user-1");
+ });
+
+ it("should delete any thread when scope is null", async () => {
+ const agent = new MockAgent(createTestEvents("User thread", "msg1"));
+
+ // Create thread for user-1
+ const obs = runner.run({
+ threadId: "thread-user1",
+ agent,
+ input: { threadId: "thread-user1", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "user-1" },
+ });
+ await firstValueFrom(obs.pipe(toArray()));
+
+ // Admin deletes thread
+ await runner.deleteThread("thread-user1", null);
+
+ // Verify thread is deleted even for the owner
+ const metadata = await runner.getThreadMetadata("thread-user1", { resourceId: "user-1" });
+ expect(metadata).toBeNull();
+ });
+
+ it("should connect to any thread when scope is null", async () => {
+ const agent = new MockAgent(createTestEvents("User message", "msg1"));
+
+ // Create thread for user-1
+ const obs = runner.run({
+ threadId: "thread-user1",
+ agent,
+ input: { threadId: "thread-user1", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "user-1" },
+ });
+ await firstValueFrom(obs.pipe(toArray()));
+
+ // Admin connects with null scope
+ const connectObs = runner.connect({
+ threadId: "thread-user1",
+ scope: null,
+ });
+
+ const events = await firstValueFrom(connectObs.pipe(toArray()));
+ expect(events.length).toBeGreaterThan(0);
+ });
+ });
+
+ describe("Properties Field", () => {
+ it("should store and retrieve properties", async () => {
+ const agent = new MockAgent(createTestEvents("Test message", "msg1"));
+
+ // Create thread with properties
+ const obs = runner.run({
+ threadId: "thread-with-props",
+ agent,
+ input: { threadId: "thread-with-props", runId: "run-1", messages: [], state: {} },
+ scope: {
+ resourceId: "user-1",
+ properties: { organizationId: "org-123", department: "engineering" },
+ },
+ });
+ await firstValueFrom(obs.pipe(toArray()));
+
+ // Get metadata and verify properties
+ const metadata = await runner.getThreadMetadata("thread-with-props", { resourceId: "user-1" });
+
+ expect(metadata).not.toBeNull();
+ expect(metadata!.properties).toEqual({
+ organizationId: "org-123",
+ department: "engineering",
+ });
+ });
+
+ it("should handle undefined properties", async () => {
+ const agent = new MockAgent(createTestEvents("Test message", "msg1"));
+
+ // Create thread without properties
+ const obs = runner.run({
+ threadId: "thread-no-props",
+ agent,
+ input: { threadId: "thread-no-props", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "user-1" },
+ });
+ await firstValueFrom(obs.pipe(toArray()));
+
+ // Get metadata and verify properties is undefined
+ const metadata = await runner.getThreadMetadata("thread-no-props", { resourceId: "user-1" });
+
+ expect(metadata).not.toBeNull();
+ expect(metadata!.properties).toBeUndefined();
+ });
+
+ it("should include properties in list results", async () => {
+ const agent = new MockAgent(createTestEvents("Test message", "msg1"));
+
+ // Create thread with properties
+ const obs = runner.run({
+ threadId: "thread-1",
+ agent,
+ input: { threadId: "thread-1", runId: "run-1", messages: [], state: {} },
+ scope: {
+ resourceId: "user-1",
+ properties: { tier: "premium", region: "us-east" },
+ },
+ });
+ await firstValueFrom(obs.pipe(toArray()));
+
+ // List threads
+ const threads = await runner.listThreads({
+ scope: { resourceId: "user-1" },
+ limit: 10,
+ });
+
+ expect(threads.threads).toHaveLength(1);
+ expect(threads.threads[0].properties).toEqual({
+ tier: "premium",
+ region: "us-east",
+ });
+ });
+ });
+});
diff --git a/packages/runtime/src/runner/__tests__/thread-hijacking.test.ts b/packages/runtime/src/runner/__tests__/thread-hijacking.test.ts
new file mode 100644
index 00000000..8065e58d
--- /dev/null
+++ b/packages/runtime/src/runner/__tests__/thread-hijacking.test.ts
@@ -0,0 +1,545 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { InMemoryAgentRunner } from "../in-memory";
+import {
+ AbstractAgent,
+ BaseEvent,
+ RunAgentInput,
+ EventType,
+ TextMessageStartEvent,
+ TextMessageContentEvent,
+ TextMessageEndEvent,
+ Message,
+} from "@ag-ui/client";
+import { EMPTY, firstValueFrom } from "rxjs";
+import { toArray } from "rxjs/operators";
+
+type RunCallbacks = {
+ onEvent: (event: { event: BaseEvent }) => void;
+ onNewMessage?: (args: { message: Message }) => void;
+ onRunStartedEvent?: () => void;
+};
+
+class MockAgent extends AbstractAgent {
+ private events: BaseEvent[];
+
+ constructor(events: BaseEvent[] = []) {
+ super();
+ this.events = events;
+ }
+
+ async runAgent(input: RunAgentInput, callbacks: RunCallbacks): Promise {
+ if (callbacks.onRunStartedEvent) {
+ callbacks.onRunStartedEvent();
+ }
+
+ for (const event of this.events) {
+ callbacks.onEvent({ event });
+ }
+ }
+
+ clone(): AbstractAgent {
+ return new MockAgent(this.events);
+ }
+
+ protected run(): ReturnType {
+ return EMPTY;
+ }
+
+ protected connect(): ReturnType {
+ return EMPTY;
+ }
+}
+
+describe("Thread Hijacking Prevention - InMemoryAgentRunner", () => {
+ let runner: InMemoryAgentRunner;
+
+ beforeEach(() => {
+ runner = new InMemoryAgentRunner();
+ runner.clearAllThreads();
+ });
+
+ const createTestEvents = (text: string, id: string): BaseEvent[] => [
+ { type: EventType.TEXT_MESSAGE_START, messageId: id, role: "user" } as TextMessageStartEvent,
+ { type: EventType.TEXT_MESSAGE_CONTENT, messageId: id, delta: text } as TextMessageContentEvent,
+ { type: EventType.TEXT_MESSAGE_END, messageId: id } as TextMessageEndEvent,
+ ];
+
+ describe("Basic Hijacking Attempts", () => {
+ it("should reject attempts to run on another user's thread", async () => {
+ const agent = new MockAgent(createTestEvents("Alice's message", "msg1"));
+
+ // Alice creates a thread
+ const aliceObs = runner.run({
+ threadId: "shared-thread-123",
+ agent,
+ input: { threadId: "shared-thread-123", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "user-alice" },
+ });
+ await firstValueFrom(aliceObs.pipe(toArray()));
+
+ // Bob tries to hijack Alice's thread
+ const bobAgent = new MockAgent(createTestEvents("Bob's hijack attempt", "msg2"));
+
+ expect(() => {
+ runner.run({
+ threadId: "shared-thread-123",
+ agent: bobAgent,
+ input: { threadId: "shared-thread-123", runId: "run-2", messages: [], state: {} },
+ scope: { resourceId: "user-bob" },
+ });
+ }).toThrow("Unauthorized: Cannot run on thread owned by different resource");
+
+ // Verify Alice's thread is untouched
+ const aliceThreads = await runner.listThreads({
+ scope: { resourceId: "user-alice" },
+ limit: 10,
+ });
+ expect(aliceThreads.threads).toHaveLength(1);
+ expect(aliceThreads.threads[0].threadId).toBe("shared-thread-123");
+ });
+
+ it("should allow legitimate user to continue their own thread", async () => {
+ const agent1 = new MockAgent(createTestEvents("Message 1", "msg1"));
+ const agent2 = new MockAgent(createTestEvents("Message 2", "msg2"));
+
+ // Alice creates a thread
+ const obs1 = runner.run({
+ threadId: "alice-thread",
+ agent: agent1,
+ input: { threadId: "alice-thread", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "user-alice" },
+ });
+ await firstValueFrom(obs1.pipe(toArray()));
+
+ // Alice continues her own thread - should work
+ const obs2 = runner.run({
+ threadId: "alice-thread",
+ agent: agent2,
+ input: { threadId: "alice-thread", runId: "run-2", messages: [], state: {} },
+ scope: { resourceId: "user-alice" },
+ });
+
+ const events = await firstValueFrom(obs2.pipe(toArray()));
+ expect(events.length).toBeGreaterThan(0);
+ });
+
+ it("should prevent hijacking with similar but different resourceIds", async () => {
+ const agent = new MockAgent(createTestEvents("Test", "msg1"));
+
+ // User alice creates thread
+ const obs1 = runner.run({
+ threadId: "thread-xyz",
+ agent,
+ input: { threadId: "thread-xyz", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "user-alice" },
+ });
+ await firstValueFrom(obs1.pipe(toArray()));
+
+ // User alice2 tries to hijack (similar name)
+ expect(() => {
+ runner.run({
+ threadId: "thread-xyz",
+ agent,
+ input: { threadId: "thread-xyz", runId: "run-2", messages: [], state: {} },
+ scope: { resourceId: "user-alice2" },
+ });
+ }).toThrow("Unauthorized");
+ });
+ });
+
+ describe("Multi-Resource Access", () => {
+ it("should allow access if user has thread's resourceId in array", async () => {
+ const agent1 = new MockAgent(createTestEvents("Workspace message", "msg1"));
+ const agent2 = new MockAgent(createTestEvents("Follow-up", "msg2"));
+
+ // Create thread in workspace
+ const obs1 = runner.run({
+ threadId: "workspace-thread",
+ agent: agent1,
+ input: { threadId: "workspace-thread", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "workspace-123" },
+ });
+ await firstValueFrom(obs1.pipe(toArray()));
+
+ // User with multi-resource access (personal + workspace)
+ const obs2 = runner.run({
+ threadId: "workspace-thread",
+ agent: agent2,
+ input: { threadId: "workspace-thread", runId: "run-2", messages: [], state: {} },
+ scope: { resourceId: ["user-alice", "workspace-123"] },
+ });
+
+ const events = await firstValueFrom(obs2.pipe(toArray()));
+ expect(events.length).toBeGreaterThan(0);
+ });
+
+ it("should reject if thread's resourceId is not in user's array", async () => {
+ const agent = new MockAgent(createTestEvents("Test", "msg1"));
+
+ // Create thread in workspace-A
+ const obs1 = runner.run({
+ threadId: "thread-a",
+ agent,
+ input: { threadId: "thread-a", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "workspace-a" },
+ });
+ await firstValueFrom(obs1.pipe(toArray()));
+
+ // User with access to workspace-B and workspace-C only
+ expect(() => {
+ runner.run({
+ threadId: "thread-a",
+ agent,
+ input: { threadId: "thread-a", runId: "run-2", messages: [], state: {} },
+ scope: { resourceId: ["workspace-b", "workspace-c"] },
+ });
+ }).toThrow("Unauthorized");
+ });
+ });
+
+ describe("Admin Bypass", () => {
+ it("should allow admin (null scope) to run on existing threads", async () => {
+ const agent1 = new MockAgent(createTestEvents("User message", "msg1"));
+ const agent2 = new MockAgent(createTestEvents("Admin reply", "msg2"));
+
+ // Regular user creates thread
+ const obs1 = runner.run({
+ threadId: "user-thread",
+ agent: agent1,
+ input: { threadId: "user-thread", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "user-alice" },
+ });
+ await firstValueFrom(obs1.pipe(toArray()));
+
+ // Admin runs on user's thread with null scope
+ const obs2 = runner.run({
+ threadId: "user-thread",
+ agent: agent2,
+ input: { threadId: "user-thread", runId: "run-2", messages: [], state: {} },
+ scope: null,
+ });
+
+ const events = await firstValueFrom(obs2.pipe(toArray()));
+ expect(events.length).toBeGreaterThan(0);
+ });
+
+ it("should reject admin attempts to create threads with null scope", () => {
+ const agent = new MockAgent(createTestEvents("Admin thread", "msg1"));
+
+ // Admin tries to create thread with null scope - should be rejected
+ expect(() => {
+ runner.run({
+ threadId: "admin-thread",
+ agent,
+ input: { threadId: "admin-thread", runId: "run-1", messages: [], state: {} },
+ scope: null,
+ });
+ }).toThrow("Cannot create thread with null scope");
+ });
+
+ it("should allow admin to list all threads with null scope", async () => {
+ const agent = new MockAgent(createTestEvents("Test", "msg1"));
+
+ // Create threads for different users
+ await firstValueFrom(
+ runner.run({
+ threadId: "alice-thread",
+ agent,
+ input: { threadId: "alice-thread", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "user-alice" },
+ }).pipe(toArray())
+ );
+
+ await firstValueFrom(
+ runner.run({
+ threadId: "bob-thread",
+ agent,
+ input: { threadId: "bob-thread", runId: "run-2", messages: [], state: {} },
+ scope: { resourceId: "user-bob" },
+ }).pipe(toArray())
+ );
+
+ // Admin can see all threads
+ const allThreads = await runner.listThreads({
+ scope: null,
+ limit: 10,
+ });
+ expect(allThreads.threads).toHaveLength(2);
+ });
+ });
+
+ describe("Empty Array Validation", () => {
+ it("should reject empty resourceId array on new thread", () => {
+ const agent = new MockAgent(createTestEvents("Test", "msg1"));
+
+ expect(() => {
+ runner.run({
+ threadId: "new-thread",
+ agent,
+ input: { threadId: "new-thread", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: [] },
+ });
+ }).toThrow("Invalid scope: resourceId array cannot be empty");
+ });
+
+ it("should reject empty resourceId array on existing thread", async () => {
+ const agent = new MockAgent(createTestEvents("Test", "msg1"));
+
+ // Create thread with valid scope
+ const obs1 = runner.run({
+ threadId: "thread-1",
+ agent,
+ input: { threadId: "thread-1", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "user-alice" },
+ });
+ await firstValueFrom(obs1.pipe(toArray()));
+
+ // Try to run with empty array
+ expect(() => {
+ runner.run({
+ threadId: "thread-1",
+ agent,
+ input: { threadId: "thread-1", runId: "run-2", messages: [], state: {} },
+ scope: { resourceId: [] },
+ });
+ }).toThrow("Invalid scope: resourceId array cannot be empty");
+ });
+ });
+
+ describe("Race Conditions", () => {
+ it("should prevent concurrent hijacking attempts", async () => {
+ const agent = new MockAgent(createTestEvents("Test", "msg1"));
+
+ // Alice creates thread
+ const obs1 = runner.run({
+ threadId: "race-thread",
+ agent,
+ input: { threadId: "race-thread", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "user-alice" },
+ });
+ await firstValueFrom(obs1.pipe(toArray()));
+
+ // Multiple users try to hijack simultaneously
+ const attempts = ["bob", "charlie", "dave"].map((user) => {
+ return new Promise((resolve) => {
+ try {
+ runner.run({
+ threadId: "race-thread",
+ agent,
+ input: { threadId: "race-thread", runId: `run-${user}`, messages: [], state: {} },
+ scope: { resourceId: `user-${user}` },
+ });
+ resolve({ user, success: true });
+ } catch (error) {
+ resolve({ user, success: false, error: (error as Error).message });
+ }
+ });
+ });
+
+ const results = await Promise.all(attempts);
+
+ // All hijacking attempts should fail
+ results.forEach((result: any) => {
+ expect(result.success).toBe(false);
+ expect(result.error).toContain("Unauthorized");
+ });
+ });
+ });
+
+ describe("Properties Preservation", () => {
+ it("should not overwrite thread properties during hijacking attempt", async () => {
+ const agent = new MockAgent(createTestEvents("Test", "msg1"));
+
+ // Alice creates thread with properties
+ const obs1 = runner.run({
+ threadId: "prop-thread",
+ agent,
+ input: { threadId: "prop-thread", runId: "run-1", messages: [], state: {} },
+ scope: {
+ resourceId: "user-alice",
+ properties: { department: "engineering", tier: "premium" },
+ },
+ });
+ await firstValueFrom(obs1.pipe(toArray()));
+
+ // Bob tries to hijack and overwrite properties
+ try {
+ runner.run({
+ threadId: "prop-thread",
+ agent,
+ input: { threadId: "prop-thread", runId: "run-2", messages: [], state: {} },
+ scope: {
+ resourceId: "user-bob",
+ properties: { department: "sales", tier: "free" },
+ },
+ });
+ } catch {
+ // Expected to fail
+ }
+
+ // Verify original properties are preserved
+ const metadata = await runner.getThreadMetadata("prop-thread", { resourceId: "user-alice" });
+ expect(metadata?.properties).toEqual({
+ department: "engineering",
+ tier: "premium",
+ });
+ });
+ });
+
+ describe("Multi-Resource Thread Persistence", () => {
+ it("should persist all resource IDs from array on thread creation", async () => {
+ const agent = new MockAgent(createTestEvents("Multi-resource message", "msg1"));
+
+ // Create thread with multiple resource IDs
+ await firstValueFrom(
+ runner.run({
+ threadId: "multi-resource-thread",
+ agent,
+ input: { threadId: "multi-resource-thread", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: ["user-123", "workspace-456"] },
+ }).pipe(toArray())
+ );
+
+ // User should be able to access it
+ const userMetadata = await runner.getThreadMetadata("multi-resource-thread", {
+ resourceId: "user-123",
+ });
+ expect(userMetadata).not.toBeNull();
+
+ // Workspace should also be able to access it
+ const workspaceMetadata = await runner.getThreadMetadata("multi-resource-thread", {
+ resourceId: "workspace-456",
+ });
+ expect(workspaceMetadata).not.toBeNull();
+
+ // Unrelated resource should not access it
+ const otherMetadata = await runner.getThreadMetadata("multi-resource-thread", {
+ resourceId: "workspace-789",
+ });
+ expect(otherMetadata).toBeNull();
+ });
+
+ it("should allow any resource owner to continue the thread", async () => {
+ const agent1 = new MockAgent(createTestEvents("First message", "msg1"));
+ const agent2 = new MockAgent(createTestEvents("Second message", "msg2"));
+ const agent3 = new MockAgent(createTestEvents("Third message", "msg3"));
+
+ // Create thread with multiple resource IDs
+ await firstValueFrom(
+ runner.run({
+ threadId: "shared-thread",
+ agent: agent1,
+ input: { threadId: "shared-thread", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: ["user-123", "workspace-456"] },
+ }).pipe(toArray())
+ );
+
+ // User can continue
+ const userEvents = await firstValueFrom(
+ runner.run({
+ threadId: "shared-thread",
+ agent: agent2,
+ input: { threadId: "shared-thread", runId: "run-2", messages: [], state: {} },
+ scope: { resourceId: "user-123" },
+ }).pipe(toArray())
+ );
+ expect(userEvents.length).toBeGreaterThan(0);
+
+ // Workspace can also continue
+ const workspaceEvents = await firstValueFrom(
+ runner.run({
+ threadId: "shared-thread",
+ agent: agent3,
+ input: { threadId: "shared-thread", runId: "run-3", messages: [], state: {} },
+ scope: { resourceId: "workspace-456" },
+ }).pipe(toArray())
+ );
+ expect(workspaceEvents.length).toBeGreaterThan(0);
+ });
+
+ it("should list thread for any of its resource owners", async () => {
+ const agent = new MockAgent(createTestEvents("Shared content", "msg1"));
+
+ // Create thread owned by both user and workspace
+ await firstValueFrom(
+ runner.run({
+ threadId: "listed-thread",
+ agent,
+ input: { threadId: "listed-thread", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: ["user-alice", "workspace-eng"] },
+ }).pipe(toArray())
+ );
+
+ // User can see it in their list
+ const userThreads = await runner.listThreads({
+ scope: { resourceId: "user-alice" },
+ limit: 10,
+ });
+ expect(userThreads.threads.some(t => t.threadId === "listed-thread")).toBe(true);
+
+ // Workspace can see it in their list
+ const workspaceThreads = await runner.listThreads({
+ scope: { resourceId: "workspace-eng" },
+ limit: 10,
+ });
+ expect(workspaceThreads.threads.some(t => t.threadId === "listed-thread")).toBe(true);
+
+ // Other workspace cannot see it
+ const otherThreads = await runner.listThreads({
+ scope: { resourceId: "workspace-sales" },
+ limit: 10,
+ });
+ expect(otherThreads.threads.some(t => t.threadId === "listed-thread")).toBe(false);
+ });
+
+ it("should prevent hijacking of multi-resource threads", async () => {
+ const agent = new MockAgent(createTestEvents("Test", "msg1"));
+
+ // Create thread owned by user and workspace
+ await firstValueFrom(
+ runner.run({
+ threadId: "protected-multi-thread",
+ agent,
+ input: { threadId: "protected-multi-thread", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: ["user-alice", "workspace-eng"] },
+ }).pipe(toArray())
+ );
+
+ // Bob tries to hijack - should fail
+ expect(() => {
+ runner.run({
+ threadId: "protected-multi-thread",
+ agent,
+ input: { threadId: "protected-multi-thread", runId: "run-2", messages: [], state: {} },
+ scope: { resourceId: "user-bob" },
+ });
+ }).toThrow("Unauthorized");
+ });
+
+ it("should allow querying with multi-resource scope", async () => {
+ const agent = new MockAgent(createTestEvents("Test", "msg1"));
+
+ // User with access to multiple workspaces creates thread in one
+ await firstValueFrom(
+ runner.run({
+ threadId: "workspace-a-thread",
+ agent,
+ input: { threadId: "workspace-a-thread", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "workspace-a" },
+ }).pipe(toArray())
+ );
+
+ // Query with multiple workspace IDs should find it
+ const metadata = await runner.getThreadMetadata("workspace-a-thread", {
+ resourceId: ["workspace-a", "workspace-b", "workspace-c"],
+ });
+ expect(metadata).not.toBeNull();
+
+ // Query without the matching ID should not find it
+ const noMatch = await runner.getThreadMetadata("workspace-a-thread", {
+ resourceId: ["workspace-b", "workspace-c"],
+ });
+ expect(noMatch).toBeNull();
+ });
+ });
+});
diff --git a/packages/runtime/src/runner/__tests__/thread-listing.test.ts b/packages/runtime/src/runner/__tests__/thread-listing.test.ts
new file mode 100644
index 00000000..56a83020
--- /dev/null
+++ b/packages/runtime/src/runner/__tests__/thread-listing.test.ts
@@ -0,0 +1,330 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { InMemoryAgentRunner } from "../in-memory";
+import {
+ AbstractAgent,
+ BaseEvent,
+ RunAgentInput,
+ EventType,
+ Message,
+ TextMessageStartEvent,
+ TextMessageContentEvent,
+ TextMessageEndEvent,
+} from "@ag-ui/client";
+import { EMPTY, firstValueFrom } from "rxjs";
+import { toArray } from "rxjs/operators";
+
+type RunCallbacks = {
+ onEvent: (event: { event: BaseEvent }) => void;
+ onNewMessage?: (args: { message: Message }) => void;
+ onRunStartedEvent?: () => void;
+};
+
+// Mock agent for testing
+class MockAgent extends AbstractAgent {
+ private events: BaseEvent[];
+
+ constructor(events: BaseEvent[] = []) {
+ super();
+ this.events = events;
+ }
+
+ async runAgent(input: RunAgentInput, callbacks: RunCallbacks): Promise {
+ if (callbacks.onRunStartedEvent) {
+ callbacks.onRunStartedEvent();
+ }
+
+ for (const event of this.events) {
+ callbacks.onEvent({ event });
+ }
+ }
+
+ clone(): AbstractAgent {
+ return new MockAgent(this.events);
+ }
+
+ protected run(): ReturnType {
+ return EMPTY;
+ }
+
+ protected connect(): ReturnType {
+ return EMPTY;
+ }
+}
+
+describe("Thread Listing - InMemoryAgentRunner", () => {
+ let runner: InMemoryAgentRunner;
+
+ beforeEach(() => {
+ runner = new InMemoryAgentRunner();
+ runner.clearAllThreads();
+ });
+
+ it("should return empty list when no threads exist", async () => {
+ const result = await runner.listThreads({ scope: { resourceId: "test-user" }, limit: 10 });
+
+ expect(result.threads).toEqual([]);
+ expect(result.total).toBe(0);
+ });
+
+ it("should list threads after runs are created", async () => {
+ const events: BaseEvent[] = [
+ { type: EventType.TEXT_MESSAGE_START, messageId: "msg1", role: "user" } as TextMessageStartEvent,
+ { type: EventType.TEXT_MESSAGE_CONTENT, messageId: "msg1", delta: "Hello World" } as TextMessageContentEvent,
+ { type: EventType.TEXT_MESSAGE_END, messageId: "msg1" } as TextMessageEndEvent,
+ ];
+
+ const agent = new MockAgent(events);
+
+ const observable1 = runner.run({
+ threadId: "thread-1",
+ agent,
+ input: { threadId: "thread-1", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "test-user" },
+ });
+ await firstValueFrom(observable1.pipe(toArray()));
+
+ const observable2 = runner.run({
+ threadId: "thread-2",
+ agent,
+ input: { threadId: "thread-2", runId: "run-2", messages: [], state: {} },
+ scope: { resourceId: "test-user" },
+ });
+ await firstValueFrom(observable2.pipe(toArray()));
+
+ const result = await runner.listThreads({ scope: { resourceId: "test-user" }, limit: 10 });
+
+ expect(result.threads).toHaveLength(2);
+ expect(result.total).toBe(2);
+ });
+
+ it("should include correct metadata", async () => {
+ const events: BaseEvent[] = [
+ { type: EventType.TEXT_MESSAGE_START, messageId: "msg-inmem", role: "user" } as TextMessageStartEvent,
+ {
+ type: EventType.TEXT_MESSAGE_CONTENT,
+ messageId: "msg-inmem",
+ delta: "In-memory message",
+ } as TextMessageContentEvent,
+ { type: EventType.TEXT_MESSAGE_END, messageId: "msg-inmem" } as TextMessageEndEvent,
+ ];
+
+ const agent = new MockAgent(events);
+ const observable = runner.run({
+ threadId: "thread-inmem",
+ agent,
+ input: { threadId: "thread-inmem", runId: "run-inmem", messages: [], state: {} },
+ scope: { resourceId: "test-user" },
+ });
+ await firstValueFrom(observable.pipe(toArray()));
+
+ const metadata = await runner.getThreadMetadata("thread-inmem", { resourceId: "test-user" });
+
+ expect(metadata).toBeDefined();
+ expect(metadata!.threadId).toBe("thread-inmem");
+ expect(metadata!.firstMessage).toBe("In-memory message");
+ });
+
+ it("should return null for non-existent thread", async () => {
+ const metadata = await runner.getThreadMetadata("non-existent", { resourceId: "test-user" });
+ expect(metadata).toBeNull();
+ });
+
+ describe("Pagination Edge Cases", () => {
+ it("should handle limit = 0", async () => {
+ const events: BaseEvent[] = [
+ { type: EventType.TEXT_MESSAGE_START, messageId: "msg1", role: "user" } as TextMessageStartEvent,
+ { type: EventType.TEXT_MESSAGE_CONTENT, messageId: "msg1", delta: "Test" } as TextMessageContentEvent,
+ { type: EventType.TEXT_MESSAGE_END, messageId: "msg1" } as TextMessageEndEvent,
+ ];
+
+ const agent = new MockAgent(events);
+
+ // Create some threads
+ for (let i = 0; i < 5; i++) {
+ await firstValueFrom(
+ runner
+ .run({
+ threadId: `thread-${i}`,
+ agent,
+ input: { threadId: `thread-${i}`, runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "test-user" },
+ })
+ .pipe(toArray()),
+ );
+ }
+
+ // Request 0 threads - should return empty array
+ const result = await runner.listThreads({ scope: { resourceId: "test-user" }, limit: 0 });
+
+ // Define expected behavior: empty results
+ expect(result.threads).toEqual([]);
+ // Total should still reflect actual count
+ expect(result.total).toBe(5);
+ });
+
+ it("should handle very large offset without performance issues", async () => {
+ const events: BaseEvent[] = [
+ { type: EventType.TEXT_MESSAGE_START, messageId: "msg1", role: "user" } as TextMessageStartEvent,
+ { type: EventType.TEXT_MESSAGE_CONTENT, messageId: "msg1", delta: "Test" } as TextMessageContentEvent,
+ { type: EventType.TEXT_MESSAGE_END, messageId: "msg1" } as TextMessageEndEvent,
+ ];
+
+ const agent = new MockAgent(events);
+
+ // Create a small number of threads
+ for (let i = 0; i < 3; i++) {
+ await firstValueFrom(
+ runner
+ .run({
+ threadId: `thread-${i}`,
+ agent,
+ input: { threadId: `thread-${i}`, runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "test-user" },
+ })
+ .pipe(toArray()),
+ );
+ }
+
+ const offset = 1_000_000;
+ const startTime = Date.now();
+
+ // Should return empty results quickly, not timeout
+ const result = await runner.listThreads({ scope: { resourceId: "test-user" }, limit: 10, offset });
+
+ const duration = Date.now() - startTime;
+
+ // Should complete quickly (under 1 second for this simple case)
+ expect(duration).toBeLessThan(1000);
+
+ // Should return empty results since offset exceeds total
+ expect(result.threads).toEqual([]);
+ expect(result.total).toBe(3);
+ });
+
+ it("should handle threads added between page fetches", async () => {
+ const events: BaseEvent[] = [
+ { type: EventType.TEXT_MESSAGE_START, messageId: "msg1", role: "user" } as TextMessageStartEvent,
+ { type: EventType.TEXT_MESSAGE_CONTENT, messageId: "msg1", delta: "Test" } as TextMessageContentEvent,
+ { type: EventType.TEXT_MESSAGE_END, messageId: "msg1" } as TextMessageEndEvent,
+ ];
+
+ const agent = new MockAgent(events);
+
+ // Create initial threads (1-10)
+ for (let i = 1; i <= 10; i++) {
+ await firstValueFrom(
+ runner
+ .run({
+ threadId: `thread-${i}`,
+ agent,
+ input: { threadId: `thread-${i}`, runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "test-user" },
+ })
+ .pipe(toArray()),
+ );
+ // Small delay to ensure consistent ordering
+ await new Promise((resolve) => setTimeout(resolve, 2));
+ }
+
+ // Fetch page 1 (threads 1-10 with limit 10, offset 0)
+ const page1 = await runner.listThreads({ scope: { resourceId: "test-user" }, limit: 10, offset: 0 });
+ expect(page1.threads).toHaveLength(10);
+ expect(page1.total).toBe(10);
+
+ // Add 5 new threads between page fetches
+ for (let i = 11; i <= 15; i++) {
+ await firstValueFrom(
+ runner
+ .run({
+ threadId: `thread-${i}`,
+ agent,
+ input: { threadId: `thread-${i}`, runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "test-user" },
+ })
+ .pipe(toArray()),
+ );
+ await new Promise((resolve) => setTimeout(resolve, 2));
+ }
+
+ // Fetch page 2 - verify consistency
+ const page2 = await runner.listThreads({ scope: { resourceId: "test-user" }, limit: 10, offset: 10 });
+
+ // Should get remaining threads
+ expect(page2.threads.length).toBeGreaterThan(0);
+ expect(page2.total).toBe(15);
+
+ // Note: Offset-based pagination with concurrent inserts can cause:
+ // - Duplicates (threads appearing in multiple pages)
+ // - Missing items (threads skipped due to offset shift)
+ // This is a known limitation of offset pagination.
+ // The test verifies the system handles this gracefully without crashing.
+
+ // Total should reflect all threads
+ expect(page2.total).toBe(15);
+
+ // Page 2 should have threads (the exact count may vary due to ordering)
+ expect(page2.threads.length).toBeLessThanOrEqual(10);
+ });
+
+ it("should handle negative offset gracefully", async () => {
+ const events: BaseEvent[] = [
+ { type: EventType.TEXT_MESSAGE_START, messageId: "msg1", role: "user" } as TextMessageStartEvent,
+ { type: EventType.TEXT_MESSAGE_CONTENT, messageId: "msg1", delta: "Test" } as TextMessageContentEvent,
+ { type: EventType.TEXT_MESSAGE_END, messageId: "msg1" } as TextMessageEndEvent,
+ ];
+
+ const agent = new MockAgent(events);
+
+ // Create some threads
+ for (let i = 0; i < 3; i++) {
+ await firstValueFrom(
+ runner
+ .run({
+ threadId: `thread-${i}`,
+ agent,
+ input: { threadId: `thread-${i}`, runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "test-user" },
+ })
+ .pipe(toArray()),
+ );
+ }
+
+ // Negative offset should be treated as 0 or return error
+ const result = await runner.listThreads({ scope: { resourceId: "test-user" }, limit: 10, offset: -5 });
+
+ // Should either treat as 0 (return results) or return empty
+ expect(result.threads.length).toBeLessThanOrEqual(3);
+ expect(result.total).toBe(3);
+ });
+
+ it("should handle limit exceeding total threads", async () => {
+ const events: BaseEvent[] = [
+ { type: EventType.TEXT_MESSAGE_START, messageId: "msg1", role: "user" } as TextMessageStartEvent,
+ { type: EventType.TEXT_MESSAGE_CONTENT, messageId: "msg1", delta: "Test" } as TextMessageContentEvent,
+ { type: EventType.TEXT_MESSAGE_END, messageId: "msg1" } as TextMessageEndEvent,
+ ];
+
+ const agent = new MockAgent(events);
+
+ // Create only 3 threads
+ for (let i = 0; i < 3; i++) {
+ await firstValueFrom(
+ runner
+ .run({
+ threadId: `thread-${i}`,
+ agent,
+ input: { threadId: `thread-${i}`, runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "test-user" },
+ })
+ .pipe(toArray()),
+ );
+ }
+
+ // Request limit of 100, should return all 3
+ const result = await runner.listThreads({ scope: { resourceId: "test-user" }, limit: 100 });
+
+ expect(result.threads).toHaveLength(3);
+ expect(result.total).toBe(3);
+ });
+ });
+});
diff --git a/packages/runtime/src/runner/__tests__/threading-edge-cases.test.ts b/packages/runtime/src/runner/__tests__/threading-edge-cases.test.ts
new file mode 100644
index 00000000..d71dd2b1
--- /dev/null
+++ b/packages/runtime/src/runner/__tests__/threading-edge-cases.test.ts
@@ -0,0 +1,1118 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { InMemoryAgentRunner } from "../in-memory";
+import {
+ AbstractAgent,
+ BaseEvent,
+ RunAgentInput,
+ EventType,
+ TextMessageStartEvent,
+ TextMessageContentEvent,
+ TextMessageEndEvent,
+ Message,
+} from "@ag-ui/client";
+import { EMPTY, firstValueFrom } from "rxjs";
+import { toArray } from "rxjs/operators";
+
+type RunCallbacks = {
+ onEvent: (event: { event: BaseEvent }) => void;
+ onNewMessage?: (args: { message: Message }) => void;
+ onRunStartedEvent?: () => void;
+};
+
+class MockAgent extends AbstractAgent {
+ private events: BaseEvent[];
+
+ constructor(events: BaseEvent[] = []) {
+ super();
+ this.events = events;
+ }
+
+ async runAgent(input: RunAgentInput, callbacks: RunCallbacks): Promise {
+ if (callbacks.onRunStartedEvent) {
+ callbacks.onRunStartedEvent();
+ }
+
+ for (const event of this.events) {
+ callbacks.onEvent({ event });
+ }
+ }
+
+ clone(): AbstractAgent {
+ return new MockAgent(this.events);
+ }
+
+ protected run(): ReturnType {
+ return EMPTY;
+ }
+
+ protected connect(): ReturnType {
+ return EMPTY;
+ }
+}
+
+describe("Threading Edge Cases - InMemoryAgentRunner", () => {
+ let runner: InMemoryAgentRunner;
+
+ beforeEach(() => {
+ runner = new InMemoryAgentRunner();
+ runner.clearAllThreads();
+ });
+
+ const createTestEvents = (text: string, id: string): BaseEvent[] => [
+ { type: EventType.TEXT_MESSAGE_START, messageId: id, role: "user" } as TextMessageStartEvent,
+ { type: EventType.TEXT_MESSAGE_CONTENT, messageId: id, delta: text } as TextMessageContentEvent,
+ { type: EventType.TEXT_MESSAGE_END, messageId: id } as TextMessageEndEvent,
+ ];
+
+ describe("Thread Creation Race Conditions", () => {
+ it("should prevent cross-user access when trying same threadId", async () => {
+ const agent1 = new MockAgent(createTestEvents("Message 1", "msg1"));
+ const agent2 = new MockAgent(createTestEvents("Message 2", "msg2"));
+
+ // Alice creates the thread first
+ await firstValueFrom(
+ runner
+ .run({
+ threadId: "concurrent-thread",
+ agent: agent1,
+ input: { threadId: "concurrent-thread", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "user-alice" },
+ })
+ .pipe(toArray()),
+ );
+
+ // Bob tries to run on Alice's thread - should be rejected
+ let errorThrown = false;
+ try {
+ await firstValueFrom(
+ runner
+ .run({
+ threadId: "concurrent-thread",
+ agent: agent2,
+ input: { threadId: "concurrent-thread", runId: "run-2", messages: [], state: {} },
+ scope: { resourceId: "user-bob" },
+ })
+ .pipe(toArray()),
+ );
+ } catch (error: any) {
+ errorThrown = true;
+ expect(error.message).toBe("Unauthorized: Cannot run on thread owned by different resource");
+ }
+ expect(errorThrown).toBe(true);
+
+ // Verify Alice still owns the thread
+ const metadata = await runner.getThreadMetadata("concurrent-thread", { resourceId: "user-alice" });
+ expect(metadata).not.toBeNull();
+ expect(metadata!.resourceId).toBe("user-alice");
+
+ // Verify Bob can't access it
+ const bobMetadata = await runner.getThreadMetadata("concurrent-thread", { resourceId: "user-bob" });
+ expect(bobMetadata).toBeNull();
+ });
+
+ it("should handle concurrent runs on same thread by same user", async () => {
+ const agent1 = new MockAgent(createTestEvents("First", "msg1"));
+ const agent2 = new MockAgent(createTestEvents("Second", "msg2"));
+
+ // Create thread first
+ await firstValueFrom(
+ runner
+ .run({
+ threadId: "sequential-thread",
+ agent: agent1,
+ input: { threadId: "sequential-thread", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "user-alice" },
+ })
+ .pipe(toArray()),
+ );
+
+ // Try to run again while "running" - should fail with "Thread already running"
+ // But since the first run completes immediately in our mock, we can't easily test this
+ // This is more of an integration test scenario
+
+ // Instead, let's verify the second run works after first completes
+ const events2 = await firstValueFrom(
+ runner
+ .run({
+ threadId: "sequential-thread",
+ agent: agent2,
+ input: { threadId: "sequential-thread", runId: "run-2", messages: [], state: {} },
+ scope: { resourceId: "user-alice" },
+ })
+ .pipe(toArray()),
+ );
+
+ expect(events2.length).toBeGreaterThan(0);
+ });
+ });
+
+ describe("Special Characters in ResourceIds", () => {
+ it("should handle unicode characters in resourceId", async () => {
+ const agent = new MockAgent(createTestEvents("Test", "msg1"));
+
+ const obs = runner.run({
+ threadId: "unicode-thread",
+ agent,
+ input: { threadId: "unicode-thread", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "user-日本語-émoji-🎉" },
+ });
+
+ const events = await firstValueFrom(obs.pipe(toArray()));
+ expect(events.length).toBeGreaterThan(0);
+
+ // Verify we can retrieve it
+ const threads = await runner.listThreads({
+ scope: { resourceId: "user-日本語-émoji-🎉" },
+ limit: 10,
+ });
+ expect(threads.total).toBe(1);
+ });
+
+ it("should handle special SQL-like characters in resourceId", async () => {
+ const agent = new MockAgent(createTestEvents("Test", "msg1"));
+
+ // These should be treated as literal strings, not SQL
+ const dangerousIds = ["user' OR '1'='1", "user--comment", "user;DROP TABLE", "user%wildcard"];
+
+ for (const resourceId of dangerousIds) {
+ const obs = runner.run({
+ threadId: `thread-${resourceId}`,
+ agent,
+ input: { threadId: `thread-${resourceId}`, runId: "run-1", messages: [], state: {} },
+ scope: { resourceId },
+ });
+
+ const events = await firstValueFrom(obs.pipe(toArray()));
+ expect(events.length).toBeGreaterThan(0);
+
+ // Verify isolation - other "users" can't access
+ const threads = await runner.listThreads({
+ scope: { resourceId: "different-user" },
+ limit: 100,
+ });
+ expect(threads.threads.find((t) => t.threadId === `thread-${resourceId}`)).toBeUndefined();
+ }
+ });
+
+ it("should handle very long resourceIds", async () => {
+ const agent = new MockAgent(createTestEvents("Test", "msg1"));
+ const longResourceId = "user-" + "a".repeat(10000); // 10KB resourceId
+
+ const obs = runner.run({
+ threadId: "long-id-thread",
+ agent,
+ input: { threadId: "long-id-thread", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: longResourceId },
+ });
+
+ const events = await firstValueFrom(obs.pipe(toArray()));
+ expect(events.length).toBeGreaterThan(0);
+
+ const metadata = await runner.getThreadMetadata("long-id-thread", { resourceId: longResourceId });
+ expect(metadata).not.toBeNull();
+ expect(metadata!.resourceId).toBe(longResourceId);
+ });
+ });
+
+ describe("ListThreads Edge Cases", () => {
+ it("should handle offset greater than total threads", async () => {
+ const agent = new MockAgent(createTestEvents("Test", "msg1"));
+
+ // Create 2 threads
+ for (let i = 0; i < 2; i++) {
+ await firstValueFrom(
+ runner
+ .run({
+ threadId: `thread-${i}`,
+ agent,
+ input: { threadId: `thread-${i}`, runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "user-alice" },
+ })
+ .pipe(toArray()),
+ );
+ }
+
+ // Request with offset beyond available threads
+ const result = await runner.listThreads({
+ scope: { resourceId: "user-alice" },
+ limit: 10,
+ offset: 100,
+ });
+
+ expect(result.total).toBe(2);
+ expect(result.threads).toHaveLength(0);
+ });
+
+ it("should return empty result for user with no threads", async () => {
+ const result = await runner.listThreads({
+ scope: { resourceId: "user-with-no-threads" },
+ limit: 10,
+ });
+
+ expect(result.total).toBe(0);
+ expect(result.threads).toHaveLength(0);
+ });
+
+ it("should handle pagination correctly", async () => {
+ const agent = new MockAgent(createTestEvents("Test", "msg1"));
+
+ // Create 10 threads
+ for (let i = 0; i < 10; i++) {
+ await firstValueFrom(
+ runner
+ .run({
+ threadId: `page-thread-${i}`,
+ agent,
+ input: { threadId: `page-thread-${i}`, runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "user-alice" },
+ })
+ .pipe(toArray()),
+ );
+ }
+
+ // Get first page
+ const page1 = await runner.listThreads({
+ scope: { resourceId: "user-alice" },
+ limit: 3,
+ offset: 0,
+ });
+
+ expect(page1.total).toBe(10);
+ expect(page1.threads).toHaveLength(3);
+
+ // Get second page
+ const page2 = await runner.listThreads({
+ scope: { resourceId: "user-alice" },
+ limit: 3,
+ offset: 3,
+ });
+
+ expect(page2.total).toBe(10);
+ expect(page2.threads).toHaveLength(3);
+
+ // Verify no overlap
+ const page1Ids = new Set(page1.threads.map((t) => t.threadId));
+ const page2Ids = new Set(page2.threads.map((t) => t.threadId));
+ const intersection = [...page1Ids].filter((id) => page2Ids.has(id));
+ expect(intersection).toHaveLength(0);
+ });
+ });
+
+ describe("Thread Lifecycle Edge Cases", () => {
+ it("should handle accessing thread immediately after deletion", async () => {
+ const agent = new MockAgent(createTestEvents("Test", "msg1"));
+
+ // Create thread
+ await firstValueFrom(
+ runner
+ .run({
+ threadId: "delete-test",
+ agent,
+ input: { threadId: "delete-test", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "user-alice" },
+ })
+ .pipe(toArray()),
+ );
+
+ // Delete it
+ await runner.deleteThread("delete-test", { resourceId: "user-alice" });
+
+ // Try to access immediately
+ const metadata = await runner.getThreadMetadata("delete-test", { resourceId: "user-alice" });
+ expect(metadata).toBeNull();
+
+ // Try to connect
+ const events = await firstValueFrom(
+ runner
+ .connect({
+ threadId: "delete-test",
+ scope: { resourceId: "user-alice" },
+ })
+ .pipe(toArray()),
+ );
+ expect(events).toHaveLength(0);
+ });
+
+ it("should allow creating thread with same ID after deletion", async () => {
+ const agent1 = new MockAgent(createTestEvents("First", "msg1"));
+ const agent2 = new MockAgent(createTestEvents("Second", "msg2"));
+
+ // Create thread
+ await firstValueFrom(
+ runner
+ .run({
+ threadId: "reuse-thread",
+ agent: agent1,
+ input: { threadId: "reuse-thread", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "user-alice" },
+ })
+ .pipe(toArray()),
+ );
+
+ // Delete it
+ await runner.deleteThread("reuse-thread", { resourceId: "user-alice" });
+
+ // Create new thread with same ID
+ const events = await firstValueFrom(
+ runner
+ .run({
+ threadId: "reuse-thread",
+ agent: agent2,
+ input: { threadId: "reuse-thread", runId: "run-2", messages: [], state: {} },
+ scope: { resourceId: "user-alice" },
+ })
+ .pipe(toArray()),
+ );
+
+ expect(events.length).toBeGreaterThan(0);
+
+ // Should only have the second run's messages
+ const allEvents = await firstValueFrom(
+ runner
+ .connect({
+ threadId: "reuse-thread",
+ scope: { resourceId: "user-alice" },
+ })
+ .pipe(toArray()),
+ );
+
+ const textEvents = allEvents.filter(
+ (e) => e.type === EventType.TEXT_MESSAGE_CONTENT,
+ ) as TextMessageContentEvent[];
+ expect(textEvents.some((e) => e.delta === "First")).toBe(false);
+ expect(textEvents.some((e) => e.delta === "Second")).toBe(true);
+ });
+ });
+
+ describe("Properties Edge Cases", () => {
+ it("should handle very large properties object", async () => {
+ const agent = new MockAgent(createTestEvents("Test", "msg1"));
+
+ // Create large properties object (100KB of data)
+ const largeProps: Record = {};
+ for (let i = 0; i < 1000; i++) {
+ largeProps[`key${i}`] = "x".repeat(100);
+ }
+
+ const obs = runner.run({
+ threadId: "large-props-thread",
+ agent,
+ input: { threadId: "large-props-thread", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "user-alice", properties: largeProps },
+ });
+
+ const events = await firstValueFrom(obs.pipe(toArray()));
+ expect(events.length).toBeGreaterThan(0);
+
+ const metadata = await runner.getThreadMetadata("large-props-thread", { resourceId: "user-alice" });
+ expect(metadata!.properties).toEqual(largeProps);
+ });
+
+ it("should handle properties with special characters", async () => {
+ const agent = new MockAgent(createTestEvents("Test", "msg1"));
+
+ const specialProps = {
+ "key with spaces": "value",
+ "key-with-dashes": "value",
+ "key.with.dots": "value",
+ "key[with]brackets": "value",
+ 日本語: "value",
+ "emoji🎉": "value",
+ };
+
+ const obs = runner.run({
+ threadId: "special-props-thread",
+ agent,
+ input: { threadId: "special-props-thread", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "user-alice", properties: specialProps },
+ });
+
+ const events = await firstValueFrom(obs.pipe(toArray()));
+ expect(events.length).toBeGreaterThan(0);
+
+ const metadata = await runner.getThreadMetadata("special-props-thread", { resourceId: "user-alice" });
+ expect(metadata!.properties).toEqual(specialProps);
+ });
+
+ it("should preserve properties across multiple runs", async () => {
+ const agent = new MockAgent(createTestEvents("Test", "msg1"));
+
+ const initialProps = { version: 1, status: "active" };
+
+ // First run with properties
+ await firstValueFrom(
+ runner
+ .run({
+ threadId: "preserve-props-thread",
+ agent,
+ input: { threadId: "preserve-props-thread", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "user-alice", properties: initialProps },
+ })
+ .pipe(toArray()),
+ );
+
+ // Second run (properties should be preserved from first run)
+ await firstValueFrom(
+ runner
+ .run({
+ threadId: "preserve-props-thread",
+ agent,
+ input: { threadId: "preserve-props-thread", runId: "run-2", messages: [], state: {} },
+ scope: { resourceId: "user-alice" },
+ })
+ .pipe(toArray()),
+ );
+
+ const metadata = await runner.getThreadMetadata("preserve-props-thread", { resourceId: "user-alice" });
+ expect(metadata!.properties).toEqual(initialProps);
+ });
+ });
+
+ describe("Connect/Disconnect Patterns", () => {
+ it("should handle multiple concurrent connections to same thread", async () => {
+ const agent = new MockAgent(createTestEvents("Test", "msg1"));
+
+ // Create thread
+ await firstValueFrom(
+ runner
+ .run({
+ threadId: "multi-connect-thread",
+ agent,
+ input: { threadId: "multi-connect-thread", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "user-alice" },
+ })
+ .pipe(toArray()),
+ );
+
+ // Connect multiple times simultaneously
+ const connections = await Promise.all([
+ firstValueFrom(
+ runner.connect({ threadId: "multi-connect-thread", scope: { resourceId: "user-alice" } }).pipe(toArray()),
+ ),
+ firstValueFrom(
+ runner.connect({ threadId: "multi-connect-thread", scope: { resourceId: "user-alice" } }).pipe(toArray()),
+ ),
+ firstValueFrom(
+ runner.connect({ threadId: "multi-connect-thread", scope: { resourceId: "user-alice" } }).pipe(toArray()),
+ ),
+ ]);
+
+ // All should receive the same events
+ expect(connections[0].length).toBe(connections[1].length);
+ expect(connections[1].length).toBe(connections[2].length);
+ });
+
+ it("should handle admin connecting to user thread", async () => {
+ const agent = new MockAgent(createTestEvents("User message", "msg1"));
+
+ // User creates thread
+ await firstValueFrom(
+ runner
+ .run({
+ threadId: "user-thread",
+ agent,
+ input: { threadId: "user-thread", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "user-alice" },
+ })
+ .pipe(toArray()),
+ );
+
+ // Admin connects (null scope)
+ const adminEvents = await firstValueFrom(
+ runner.connect({ threadId: "user-thread", scope: null }).pipe(toArray()),
+ );
+
+ expect(adminEvents.length).toBeGreaterThan(0);
+
+ // Admin with undefined scope
+ const globalEvents = await firstValueFrom(runner.connect({ threadId: "user-thread" }).pipe(toArray()));
+
+ expect(globalEvents.length).toBeGreaterThan(0);
+ });
+
+ it("should return empty for non-existent thread connections", async () => {
+ const events = await firstValueFrom(
+ runner.connect({ threadId: "does-not-exist", scope: { resourceId: "user-alice" } }).pipe(toArray()),
+ );
+
+ expect(events).toHaveLength(0);
+ });
+ });
+
+ describe("Resource ID Array Edge Cases", () => {
+ it("should handle duplicate IDs in resourceId array", async () => {
+ const agent = new MockAgent(createTestEvents("Test", "msg1"));
+
+ // Create thread
+ await firstValueFrom(
+ runner
+ .run({
+ threadId: "dup-array-thread",
+ agent,
+ input: { threadId: "dup-array-thread", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "workspace-a" },
+ })
+ .pipe(toArray()),
+ );
+
+ // Access with duplicate IDs in array
+ const threads = await runner.listThreads({
+ scope: { resourceId: ["workspace-a", "workspace-a", "workspace-a"] },
+ limit: 10,
+ });
+
+ expect(threads.total).toBe(1);
+ expect(threads.threads[0].threadId).toBe("dup-array-thread");
+ });
+
+ it("should handle very large resourceId arrays", async () => {
+ const agent = new MockAgent(createTestEvents("Test", "msg1"));
+
+ // Create threads for different workspaces
+ for (let i = 0; i < 5; i++) {
+ await firstValueFrom(
+ runner
+ .run({
+ threadId: `workspace-thread-${i}`,
+ agent,
+ input: { threadId: `workspace-thread-${i}`, runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: `workspace-${i}` },
+ })
+ .pipe(toArray()),
+ );
+ }
+
+ // Query with large array (100+ workspaces)
+ const largeArray = Array.from({ length: 100 }, (_, i) => `workspace-${i}`);
+ const threads = await runner.listThreads({
+ scope: { resourceId: largeArray },
+ limit: 100,
+ });
+
+ // Should find the 5 we created
+ expect(threads.total).toBe(5);
+ });
+
+ it("should handle single element array same as string", async () => {
+ const agent = new MockAgent(createTestEvents("Test", "msg1"));
+
+ // Create with string
+ await firstValueFrom(
+ runner
+ .run({
+ threadId: "single-array-thread",
+ agent,
+ input: { threadId: "single-array-thread", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "user-alice" },
+ })
+ .pipe(toArray()),
+ );
+
+ // Query with single-element array
+ const threads = await runner.listThreads({
+ scope: { resourceId: ["user-alice"] },
+ limit: 10,
+ });
+
+ expect(threads.total).toBe(1);
+ expect(threads.threads[0].threadId).toBe("single-array-thread");
+ });
+ });
+
+ describe("Suggestion Threads", () => {
+ it("should filter out suggestion threads from listThreads", async () => {
+ const agent = new MockAgent(createTestEvents("Test", "msg1"));
+
+ // Create regular thread
+ await firstValueFrom(
+ runner
+ .run({
+ threadId: "regular-thread",
+ agent,
+ input: { threadId: "regular-thread", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "user-alice" },
+ })
+ .pipe(toArray()),
+ );
+
+ // Create suggestion thread (contains "-suggestions-")
+ await firstValueFrom(
+ runner
+ .run({
+ threadId: "thread-suggestions-123",
+ agent,
+ input: { threadId: "thread-suggestions-123", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "user-alice" },
+ })
+ .pipe(toArray()),
+ );
+
+ // List threads should exclude suggestions
+ const threads = await runner.listThreads({
+ scope: { resourceId: "user-alice" },
+ limit: 10,
+ });
+
+ expect(threads.total).toBe(1);
+ expect(threads.threads[0].threadId).toBe("regular-thread");
+ });
+
+ it("should allow direct access to suggestion threads via getThreadMetadata", async () => {
+ const agent = new MockAgent(createTestEvents("Test", "msg1"));
+
+ // Create suggestion thread
+ await firstValueFrom(
+ runner
+ .run({
+ threadId: "my-suggestions-thread",
+ agent,
+ input: { threadId: "my-suggestions-thread", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "user-alice" },
+ })
+ .pipe(toArray()),
+ );
+
+ // Should be able to get metadata directly
+ const metadata = await runner.getThreadMetadata("my-suggestions-thread", { resourceId: "user-alice" });
+ expect(metadata).not.toBeNull();
+ expect(metadata!.threadId).toBe("my-suggestions-thread");
+ });
+
+ it("should respect scope for suggestion threads", async () => {
+ const agent = new MockAgent(createTestEvents("Test", "msg1"));
+
+ // Alice creates suggestion thread
+ await firstValueFrom(
+ runner
+ .run({
+ threadId: "alice-suggestions-thread",
+ agent,
+ input: { threadId: "alice-suggestions-thread", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "user-alice" },
+ })
+ .pipe(toArray()),
+ );
+
+ // Bob shouldn't be able to access Alice's suggestions
+ const metadata = await runner.getThreadMetadata("alice-suggestions-thread", { resourceId: "user-bob" });
+ expect(metadata).toBeNull();
+ });
+ });
+
+ describe("Deletion During Active Operations", () => {
+ it("should handle deleting a currently running thread", async () => {
+ // Create a long-running agent that can be interrupted
+ let runStarted = false;
+ let runCompleted = false;
+
+ const longRunningEvents: BaseEvent[] = [
+ { type: EventType.TEXT_MESSAGE_START, messageId: "msg1", role: "user" } as TextMessageStartEvent,
+ { type: EventType.TEXT_MESSAGE_CONTENT, messageId: "msg1", delta: "Starting..." } as TextMessageContentEvent,
+ ];
+
+ class SlowAgent extends MockAgent {
+ async runAgent(input: RunAgentInput, callbacks: RunCallbacks): Promise {
+ runStarted = true;
+ if (callbacks.onRunStartedEvent) {
+ callbacks.onRunStartedEvent();
+ }
+
+ // Emit first events
+ for (const event of longRunningEvents) {
+ callbacks.onEvent({ event });
+ }
+
+ // Simulate long-running operation
+ await new Promise((resolve) => setTimeout(resolve, 100));
+
+ // Emit end event
+ callbacks.onEvent({
+ event: { type: EventType.TEXT_MESSAGE_END, messageId: "msg1" } as TextMessageEndEvent,
+ });
+
+ runCompleted = true;
+ }
+ }
+
+ const agent = new SlowAgent();
+
+ // Start the run
+ const observable = runner.run({
+ threadId: "running-thread",
+ agent,
+ input: { threadId: "running-thread", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "test-user" },
+ });
+
+ // Start consuming the observable (don't await yet)
+ const runPromise = firstValueFrom(observable.pipe(toArray()));
+
+ // Wait for run to start
+ await new Promise((resolve) => setTimeout(resolve, 20));
+ expect(runStarted).toBe(true);
+
+ // Delete the thread mid-run
+ await runner.deleteThread("running-thread", { resourceId: "test-user" });
+
+ // Verify thread is deleted
+ const metadata = await runner.getThreadMetadata("running-thread", { resourceId: "test-user" });
+ expect(metadata).toBeNull();
+
+ // The run should complete (or be terminated)
+ try {
+ await runPromise;
+ } catch (error) {
+ // May throw if properly canceled
+ }
+
+ // Thread should remain deleted
+ const stillDeleted = await runner.getThreadMetadata("running-thread", { resourceId: "test-user" });
+ expect(stillDeleted).toBeNull();
+ });
+
+ it("should handle concurrent deletion of the same thread", async () => {
+ const agent = new MockAgent(createTestEvents("Test message", "msg1"));
+
+ // Create a thread
+ await firstValueFrom(
+ runner
+ .run({
+ threadId: "concurrent-delete-thread",
+ agent,
+ input: { threadId: "concurrent-delete-thread", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "test-user" },
+ })
+ .pipe(toArray()),
+ );
+
+ // Verify thread exists
+ const beforeDelete = await runner.getThreadMetadata("concurrent-delete-thread", { resourceId: "test-user" });
+ expect(beforeDelete).not.toBeNull();
+
+ // Delete the same thread concurrently (both should succeed - idempotent)
+ await Promise.all([
+ runner.deleteThread("concurrent-delete-thread", { resourceId: "test-user" }),
+ runner.deleteThread("concurrent-delete-thread", { resourceId: "test-user" }),
+ ]);
+
+ // Both deletions should complete without throwing errors
+
+ // Thread should be deleted
+ const afterDelete = await runner.getThreadMetadata("concurrent-delete-thread", { resourceId: "test-user" });
+ expect(afterDelete).toBeNull();
+
+ // Verify it's removed from the list
+ const list = await runner.listThreads({ scope: { resourceId: "test-user" }, limit: 10 });
+ expect(list.threads.find((t) => t.threadId === "concurrent-delete-thread")).toBeUndefined();
+ });
+
+ it("should restore thread to original position on deletion rollback", async () => {
+ const agent = new MockAgent(createTestEvents("Test", "msg"));
+
+ // Create multiple threads in a specific order
+ for (let i = 1; i <= 7; i++) {
+ await firstValueFrom(
+ runner
+ .run({
+ threadId: `thread-${i}`,
+ agent,
+ input: { threadId: `thread-${i}`, runId: `run-${i}`, messages: [], state: {} },
+ scope: { resourceId: "test-user" },
+ })
+ .pipe(toArray()),
+ );
+ // Small delay to ensure ordering by lastActivityAt
+ await new Promise((resolve) => setTimeout(resolve, 5));
+ }
+
+ // Verify thread-5 is at a specific position
+ const beforeList = await runner.listThreads({ scope: { resourceId: "test-user" }, limit: 10 });
+ expect(beforeList.threads).toHaveLength(7);
+ const thread5Index = beforeList.threads.findIndex((t) => t.threadId === "thread-5");
+ expect(thread5Index).toBe(2); // Should be at index 2 (third from most recent)
+
+ // Delete thread-5
+ await runner.deleteThread("thread-5", { resourceId: "test-user" });
+
+ // Verify it's deleted
+ const afterDelete = await runner.listThreads({ scope: { resourceId: "test-user" }, limit: 10 });
+ expect(afterDelete.threads).toHaveLength(6);
+ expect(afterDelete.threads.find((t) => t.threadId === "thread-5")).toBeUndefined();
+
+ // In a real implementation with rollback support, if the server fails:
+ // - An optimistic UI update would need to be rolled back
+ // - The thread should be restored to its original position (index 2)
+ // - Not appended to the end of the list
+
+ // For InMemoryRunner, once deleted it's gone, but this test structure
+ // demonstrates the expected behavior for rollback scenarios
+ expect(afterDelete.threads.find((t) => t.threadId === "thread-5")).toBeUndefined();
+ });
+ });
+
+ describe("Thread ID URL Encoding", () => {
+ it("should handle thread ID with forward slashes", async () => {
+ const agent = new MockAgent(createTestEvents("Message with slashes", "msg1"));
+ const threadId = "user/workspace/thread";
+
+ // Create thread with slashes in ID
+ await firstValueFrom(
+ runner
+ .run({
+ threadId,
+ agent,
+ input: { threadId, runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "test-user" },
+ })
+ .pipe(toArray()),
+ );
+
+ // Fetch thread metadata - should properly encode/decode
+ const metadata = await runner.getThreadMetadata(threadId, { resourceId: "test-user" });
+ expect(metadata).not.toBeNull();
+ expect(metadata!.threadId).toBe(threadId);
+
+ // List threads should include it
+ const list = await runner.listThreads({ scope: { resourceId: "test-user" }, limit: 10 });
+ expect(list.threads.find((t) => t.threadId === threadId)).toBeDefined();
+
+ // Delete should work
+ await runner.deleteThread(threadId, { resourceId: "test-user" });
+ const afterDelete = await runner.getThreadMetadata(threadId, { resourceId: "test-user" });
+ expect(afterDelete).toBeNull();
+ });
+
+ it("should handle thread ID with special characters", async () => {
+ const agent = new MockAgent(createTestEvents("Special chars", "msg1"));
+ const threadId = "thread?foo=bar&baz=qux#hash";
+
+ // Create thread with special URL characters
+ await firstValueFrom(
+ runner
+ .run({
+ threadId,
+ agent,
+ input: { threadId, runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "test-user" },
+ })
+ .pipe(toArray()),
+ );
+
+ // Verify it was created correctly
+ const metadata = await runner.getThreadMetadata(threadId, { resourceId: "test-user" });
+ expect(metadata).not.toBeNull();
+ expect(metadata!.threadId).toBe(threadId);
+
+ // Should handle URL-like characters without parsing errors
+ const list = await runner.listThreads({ scope: { resourceId: "test-user" }, limit: 10 });
+ const found = list.threads.find((t) => t.threadId === threadId);
+ expect(found).toBeDefined();
+ expect(found!.threadId).toBe(threadId);
+ });
+
+ it("should handle thread ID with percent signs", async () => {
+ const agent = new MockAgent(createTestEvents("Percent test", "msg1"));
+ const threadId = "thread%20with%20percents";
+
+ // Create thread with percent-encoded-like characters
+ await firstValueFrom(
+ runner
+ .run({
+ threadId,
+ agent,
+ input: { threadId, runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "test-user" },
+ })
+ .pipe(toArray()),
+ );
+
+ // Verify no double-encoding issues
+ const metadata = await runner.getThreadMetadata(threadId, { resourceId: "test-user" });
+ expect(metadata).not.toBeNull();
+ expect(metadata!.threadId).toBe(threadId);
+ // Should preserve the literal percent signs, not decode them
+ expect(metadata!.threadId).not.toBe("thread with percents");
+
+ // Connect should work with the exact ID
+ const events = await firstValueFrom(
+ runner.connect({ threadId, scope: { resourceId: "test-user" } }).pipe(toArray()),
+ );
+ expect(events.length).toBeGreaterThan(0);
+ });
+
+ it("should reject empty or whitespace-only thread IDs", async () => {
+ const agent = new MockAgent(createTestEvents("Test", "msg1"));
+ const invalidIds = ["", " ", "\t\n", " "];
+
+ for (const threadId of invalidIds) {
+ // Attempt to create thread with invalid ID
+ let errorThrown = false;
+ try {
+ await firstValueFrom(
+ runner
+ .run({
+ threadId,
+ agent,
+ input: { threadId, runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "test-user" },
+ })
+ .pipe(toArray()),
+ );
+ } catch (error: any) {
+ errorThrown = true;
+ // Should reject with clear error message
+ expect(error.message).toBeTruthy();
+ }
+
+ // For InMemoryRunner, it may allow empty IDs, but in production
+ // these should be rejected. This test documents the expected behavior.
+ // If no error was thrown, at least verify the thread ID is preserved as-is
+ if (!errorThrown) {
+ const metadata = await runner.getThreadMetadata(threadId, { resourceId: "test-user" });
+ if (metadata) {
+ expect(metadata.threadId).toBe(threadId);
+ }
+ }
+ }
+ });
+ });
+
+ describe("First Message Truncation", () => {
+ it("should not truncate message with exactly 100 characters", async () => {
+ const exactMessage = "a".repeat(100);
+ const agent = new MockAgent(createTestEvents(exactMessage, "msg1"));
+
+ await firstValueFrom(
+ runner
+ .run({
+ threadId: "exact-100-thread",
+ agent,
+ input: { threadId: "exact-100-thread", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "test-user" },
+ })
+ .pipe(toArray()),
+ );
+
+ const metadata = await runner.getThreadMetadata("exact-100-thread", { resourceId: "test-user" });
+ expect(metadata).not.toBeNull();
+ // Message with exactly 100 characters should be preserved fully
+ expect(metadata!.firstMessage).toBe(exactMessage);
+ expect(metadata!.firstMessage?.length).toBe(100);
+ });
+
+ it("should truncate at 100 without splitting multi-byte UTF-8 characters", async () => {
+ // Create a message with ASCII chars + emojis that would cause split at boundary
+ const message = "a".repeat(98) + "🎉🎉"; // 98 + 2 emojis (each emoji is multiple bytes)
+ const agent = new MockAgent(createTestEvents(message, "msg1"));
+
+ await firstValueFrom(
+ runner
+ .run({
+ threadId: "emoji-truncate-thread",
+ agent,
+ input: { threadId: "emoji-truncate-thread", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "test-user" },
+ })
+ .pipe(toArray()),
+ );
+
+ const metadata = await runner.getThreadMetadata("emoji-truncate-thread", { resourceId: "test-user" });
+ expect(metadata).not.toBeNull();
+
+ // If truncation happens, it should not create invalid UTF-8
+ // The firstMessage should be a valid string (no broken emoji characters)
+ const firstMessage = metadata!.firstMessage || "";
+ expect(firstMessage).toBeTruthy();
+
+ // Verify the string is valid UTF-8 by checking it doesn't contain replacement characters
+ // when re-encoded (a sign of invalid UTF-8)
+ expect(firstMessage).not.toContain("\uFFFD"); // Unicode replacement character
+
+ // If truncated, should preserve complete characters only
+ if (firstMessage.length < message.length) {
+ // Last character should be a complete character, not a broken emoji
+ const lastChar = firstMessage[firstMessage.length - 1];
+ expect(lastChar).toBeTruthy();
+ }
+ });
+
+ it("should handle firstMessage with only whitespace", async () => {
+ const whitespaceMessage = "\n\n\n\t \n";
+ const agent = new MockAgent(createTestEvents(whitespaceMessage, "msg1"));
+
+ await firstValueFrom(
+ runner
+ .run({
+ threadId: "whitespace-thread",
+ agent,
+ input: { threadId: "whitespace-thread", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "test-user" },
+ })
+ .pipe(toArray()),
+ );
+
+ const metadata = await runner.getThreadMetadata("whitespace-thread", { resourceId: "test-user" });
+ expect(metadata).not.toBeNull();
+
+ // Should handle gracefully - either preserve whitespace or show empty
+ expect(metadata!.firstMessage).toBeDefined();
+ // The implementation may choose to preserve or trim whitespace
+ // This test ensures it doesn't crash
+ });
+
+ it("should handle threads with zero messages", async () => {
+ // Create a mock agent that sends no message events
+ const emptyAgent = new MockAgent([]);
+
+ await firstValueFrom(
+ runner
+ .run({
+ threadId: "empty-message-thread",
+ agent: emptyAgent,
+ input: { threadId: "empty-message-thread", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "test-user" },
+ })
+ .pipe(toArray()),
+ );
+
+ const metadata = await runner.getThreadMetadata("empty-message-thread", { resourceId: "test-user" });
+ expect(metadata).not.toBeNull();
+
+ // firstMessage should be undefined or empty string for threads with no messages
+ const firstMessage = metadata!.firstMessage;
+ expect(firstMessage === undefined || firstMessage === "" || firstMessage === null).toBe(true);
+ });
+
+ it("should handle very long messages (over 100 chars)", async () => {
+ const longMessage = "a".repeat(500);
+ const agent = new MockAgent(createTestEvents(longMessage, "msg1"));
+
+ await firstValueFrom(
+ runner
+ .run({
+ threadId: "long-message-thread",
+ agent,
+ input: { threadId: "long-message-thread", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "test-user" },
+ })
+ .pipe(toArray()),
+ );
+
+ const metadata = await runner.getThreadMetadata("long-message-thread", { resourceId: "test-user" });
+ expect(metadata).not.toBeNull();
+
+ const firstMessage = metadata!.firstMessage || "";
+
+ // Should truncate or handle long messages appropriately
+ // Most implementations truncate to ~100 chars for performance
+ if (firstMessage.length < longMessage.length) {
+ // If truncated, should be around 100 chars
+ expect(firstMessage.length).toBeLessThanOrEqual(105); // Small buffer for ellipsis or boundary
+ expect(firstMessage.length).toBeGreaterThan(0);
+ } else {
+ // If not truncated, should preserve the full message
+ expect(firstMessage).toBe(longMessage);
+ }
+ });
+ });
+});
diff --git a/packages/runtime/src/runner/agent-runner.ts b/packages/runtime/src/runner/agent-runner.ts
index 8c102624..128d7b32 100644
--- a/packages/runtime/src/runner/agent-runner.ts
+++ b/packages/runtime/src/runner/agent-runner.ts
@@ -1,14 +1,32 @@
import { AbstractAgent, BaseEvent, RunAgentInput } from "@ag-ui/client";
import { Observable } from "rxjs";
+import { ThreadMetadata } from "@copilotkitnext/shared";
+
+// Re-export ThreadMetadata for convenience
+export type { ThreadMetadata };
+
+/**
+ * Resource scope for thread access control.
+ *
+ * @property resourceId - Primary isolation dimension (indexed, fast queries).
+ * Can be a single string or array of strings for multi-resource access.
+ * @property properties - Optional metadata (flexible, slower JSON queries).
+ */
+export interface ResourceScope {
+ resourceId: string | string[];
+ properties?: Record;
+}
export interface AgentRunnerRunRequest {
threadId: string;
agent: AbstractAgent;
input: RunAgentInput;
+ scope?: ResourceScope | null;
}
export interface AgentRunnerConnectRequest {
threadId: string;
+ scope?: ResourceScope | null;
}
export interface AgentRunnerIsRunningRequest {
@@ -19,9 +37,23 @@ export interface AgentRunnerStopRequest {
threadId: string;
}
+export interface AgentRunnerListThreadsRequest {
+ scope?: ResourceScope | null;
+ limit?: number;
+ offset?: number;
+}
+
+export interface AgentRunnerListThreadsResponse {
+ threads: ThreadMetadata[];
+ total: number;
+}
+
export abstract class AgentRunner {
abstract run(request: AgentRunnerRunRequest): Observable;
abstract connect(request: AgentRunnerConnectRequest): Observable;
abstract isRunning(request: AgentRunnerIsRunningRequest): Promise;
abstract stop(request: AgentRunnerStopRequest): Promise;
+ abstract listThreads(request: AgentRunnerListThreadsRequest): Promise;
+ abstract getThreadMetadata(threadId: string, scope?: ResourceScope | null): Promise;
+ abstract deleteThread(threadId: string, scope?: ResourceScope | null): Promise;
}
diff --git a/packages/runtime/src/runner/in-memory.ts b/packages/runtime/src/runner/in-memory.ts
index 2c8f02b4..670adf03 100644
--- a/packages/runtime/src/runner/in-memory.ts
+++ b/packages/runtime/src/runner/in-memory.ts
@@ -4,7 +4,10 @@ import {
AgentRunnerIsRunningRequest,
AgentRunnerRunRequest,
type AgentRunnerStopRequest,
+ type AgentRunnerListThreadsRequest,
+ type AgentRunnerListThreadsResponse,
} from "./agent-runner";
+import { ThreadMetadata } from "@copilotkitnext/shared";
import { Observable, ReplaySubject } from "rxjs";
import {
AbstractAgent,
@@ -12,6 +15,7 @@ import {
EventType,
MessagesSnapshotEvent,
RunStartedEvent,
+ TextMessageContentEvent,
compactEvents,
} from "@ag-ui/client";
import { finalizeRunEvents } from "./finalize-events";
@@ -25,7 +29,11 @@ interface HistoricRun {
}
class InMemoryEventStore {
- constructor(public threadId: string) {}
+ constructor(
+ public threadId: string,
+ public resourceIds: string[],
+ public properties?: Record,
+ ) {}
/** The subject that current consumers subscribe to. */
subject: ReplaySubject | null = null;
@@ -54,11 +62,63 @@ class InMemoryEventStore {
const GLOBAL_STORE = new Map();
+/**
+ * Check if a store's resourceIds match the given scope.
+ * Returns true if scope is undefined (global), null (admin bypass), or if ANY store resourceId matches ANY scope resourceId.
+ */
+function matchesScope(store: InMemoryEventStore, scope: { resourceId: string | string[] } | null | undefined): boolean {
+ if (scope === undefined || scope === null) {
+ return true; // Undefined (global) or null (admin) - see all threads
+ }
+
+ const scopeIds = Array.isArray(scope.resourceId) ? scope.resourceId : [scope.resourceId];
+ // Check if ANY scope ID matches ANY of the thread's resource IDs
+ return scopeIds.some((scopeId) => store.resourceIds.includes(scopeId));
+}
+
export class InMemoryAgentRunner extends AgentRunner {
run(request: AgentRunnerRunRequest): Observable {
+ // Check if thread exists first
let existingStore = GLOBAL_STORE.get(request.threadId);
- if (!existingStore) {
- existingStore = new InMemoryEventStore(request.threadId);
+
+ // SECURITY: Prevent null scope on NEW thread creation (admin must specify explicit owner)
+ // BUT allow null scope for existing threads (admin bypass)
+ if (!existingStore && request.scope === null) {
+ throw new Error(
+ "Cannot create thread with null scope. Admin users must specify an explicit resourceId for the thread owner.",
+ );
+ }
+
+ // Handle scope: undefined (not provided) defaults to global, or explicit value(s)
+ let resourceIds: string[];
+ if (request.scope === undefined) {
+ // No scope provided - default to global
+ resourceIds = ["global"];
+ } else if (request.scope === null) {
+ // Null scope on existing thread (admin bypass) - use existing resource IDs
+ resourceIds = [];
+ } else if (Array.isArray(request.scope.resourceId)) {
+ // Reject empty arrays - unclear intent
+ if (request.scope.resourceId.length === 0) {
+ throw new Error("Invalid scope: resourceId array cannot be empty");
+ }
+ // Store ALL resource IDs for multi-resource threads
+ resourceIds = request.scope.resourceId;
+ } else {
+ resourceIds = [request.scope.resourceId];
+ }
+
+ // SECURITY: Validate scope before allowing operations on existing threads
+ if (existingStore) {
+ // Thread exists - validate scope matches (null scope bypasses this check)
+ if (request.scope !== null && !matchesScope(existingStore, request.scope)) {
+ throw new Error("Unauthorized: Cannot run on thread owned by different resource");
+ }
+ // For existing threads, use existing resource IDs (don't add new ones)
+ resourceIds = existingStore.resourceIds;
+ } else {
+ // Create new thread store with validated scope - store ALL resource IDs
+ existingStore = new InMemoryEventStore(request.threadId, resourceIds, request.scope?.properties);
GLOBAL_STORE.set(request.threadId, existingStore);
}
const store = existingStore; // Now store is const and non-null
@@ -117,15 +177,11 @@ export class InMemoryAgentRunner extends AgentRunner {
const runStartedEvent = event as RunStartedEvent;
if (!runStartedEvent.input) {
const sanitizedMessages = request.input.messages
- ? request.input.messages.filter(
- (message) => !historicMessageIds.has(message.id),
- )
+ ? request.input.messages.filter((message) => !historicMessageIds.has(message.id))
: undefined;
const updatedInput = {
...request.input,
- ...(sanitizedMessages !== undefined
- ? { messages: sanitizedMessages }
- : {}),
+ ...(sanitizedMessages !== undefined ? { messages: sanitizedMessages } : {}),
};
processedEvent = {
...runStartedEvent,
@@ -243,8 +299,8 @@ export class InMemoryAgentRunner extends AgentRunner {
const store = GLOBAL_STORE.get(request.threadId);
const connectionSubject = new ReplaySubject(Infinity);
- if (!store) {
- // No store means no events
+ if (!store || !matchesScope(store, request.scope)) {
+ // No store or scope mismatch - return empty (404)
connectionSubject.complete();
return connectionSubject.asObservable();
}
@@ -272,11 +328,7 @@ export class InMemoryAgentRunner extends AgentRunner {
store.subject.subscribe({
next: (event) => {
// Skip message events that we've already emitted from historic
- if (
- "messageId" in event &&
- typeof event.messageId === "string" &&
- emittedMessageIds.has(event.messageId)
- ) {
+ if ("messageId" in event && typeof event.messageId === "string" && emittedMessageIds.has(event.messageId)) {
return;
}
connectionSubject.next(event);
@@ -297,33 +349,212 @@ export class InMemoryAgentRunner extends AgentRunner {
return Promise.resolve(store?.isRunning ?? false);
}
- stop(request: AgentRunnerStopRequest): Promise {
+ async stop(request: AgentRunnerStopRequest): Promise {
const store = GLOBAL_STORE.get(request.threadId);
- if (!store || !store.isRunning) {
- return Promise.resolve(false);
+ if (!store) {
+ return false;
}
- if (store.stopRequested) {
- return Promise.resolve(false);
+
+ if (store.isRunning) {
+ store.stopRequested = true;
+ store.isRunning = false;
+
+ const agent = store.agent;
+
+ try {
+ // Use agent.abortRun() to stop the run
+ if (agent) {
+ agent.abortRun();
+ return true;
+ }
+ return false;
+ } catch (error) {
+ console.warn("Failed to abort in-memory runner:", error);
+ store.stopRequested = false;
+ store.isRunning = true;
+ return false;
+ }
}
- store.stopRequested = true;
- store.isRunning = false;
+ return false;
+ }
+
+ async listThreads(request: AgentRunnerListThreadsRequest): Promise {
+ const limit = request.limit ?? 50;
+ const offset = request.offset ?? 0;
- const agent = store.agent;
- if (!agent) {
- store.stopRequested = false;
- store.isRunning = false;
- return Promise.resolve(false);
+ // Short-circuit: empty array means no access to any threads
+ if (request.scope !== undefined && request.scope !== null) {
+ const scopeIds = Array.isArray(request.scope.resourceId) ? request.scope.resourceId : [request.scope.resourceId];
+
+ if (scopeIds.length === 0) {
+ return { threads: [], total: 0 };
+ }
}
- try {
- agent.abortRun();
- return Promise.resolve(true);
- } catch (error) {
- console.error("Failed to abort agent run", error);
- store.stopRequested = false;
- store.isRunning = true;
- return Promise.resolve(false);
+ // Get all thread IDs and sort by last activity
+ const threadInfos: Array<{
+ threadId: string;
+ createdAt: number;
+ lastActivityAt: number;
+ store: InMemoryEventStore;
+ }> = [];
+
+ for (const [threadId, store] of GLOBAL_STORE.entries()) {
+ // Skip suggestion threads
+ if (threadId.includes("-suggestions-")) {
+ continue;
+ }
+
+ // Filter by scope
+ if (!matchesScope(store, request.scope)) {
+ continue;
+ }
+
+ if (store.historicRuns.length === 0) {
+ continue; // Skip threads with no runs
+ }
+
+ const firstRun = store.historicRuns[0];
+ const lastRun = store.historicRuns[store.historicRuns.length - 1];
+
+ if (!firstRun || !lastRun) {
+ continue; // Skip if no runs
+ }
+
+ threadInfos.push({
+ threadId,
+ createdAt: firstRun.createdAt,
+ lastActivityAt: lastRun.createdAt,
+ store,
+ });
+ }
+
+ // Sort by last activity (most recent first)
+ threadInfos.sort((a, b) => b.lastActivityAt - a.lastActivityAt);
+
+ const total = threadInfos.length;
+ const paginatedInfos = threadInfos.slice(offset, offset + limit);
+
+ const threads: ThreadMetadata[] = paginatedInfos.map((info) => {
+ // Extract first message from first run
+ let firstMessage: string | undefined;
+ const firstRun = info.store.historicRuns[0];
+ if (firstRun) {
+ const textContent = firstRun.events.find((e) => e.type === EventType.TEXT_MESSAGE_CONTENT) as
+ | TextMessageContentEvent
+ | undefined;
+ if (textContent?.delta) {
+ firstMessage = textContent.delta.substring(0, 100);
+ }
+ }
+
+ // Count unique messages across all runs
+ const messageIds = new Set();
+ for (const run of info.store.historicRuns) {
+ for (const event of run.events) {
+ if ("messageId" in event && typeof event.messageId === "string") {
+ messageIds.add(event.messageId);
+ }
+ }
+ }
+
+ return {
+ threadId: info.threadId,
+ createdAt: info.createdAt,
+ lastActivityAt: info.lastActivityAt,
+ isRunning: info.store.isRunning,
+ messageCount: messageIds.size,
+ firstMessage,
+ resourceId: info.store.resourceIds[0] || "unknown", // Return first for backward compatibility
+ properties: info.store.properties,
+ };
+ });
+
+ return { threads, total };
+ }
+
+ async getThreadMetadata(
+ threadId: string,
+ scope?: { resourceId: string | string[] } | null,
+ ): Promise {
+ const store = GLOBAL_STORE.get(threadId);
+ if (!store || !matchesScope(store, scope) || store.historicRuns.length === 0) {
+ return null;
+ }
+
+ const firstRun = store.historicRuns[0];
+ const lastRun = store.historicRuns[store.historicRuns.length - 1];
+
+ if (!firstRun || !lastRun) {
+ return null;
+ }
+
+ // Extract first message
+ let firstMessage: string | undefined;
+ const textContent = firstRun.events.find((e) => e.type === EventType.TEXT_MESSAGE_CONTENT) as
+ | TextMessageContentEvent
+ | undefined;
+ if (textContent?.delta) {
+ firstMessage = textContent.delta.substring(0, 100);
+ }
+
+ // Count unique messages
+ const messageIds = new Set();
+ for (const run of store.historicRuns) {
+ for (const event of run.events) {
+ if ("messageId" in event && typeof event.messageId === "string") {
+ messageIds.add(event.messageId);
+ }
+ }
+ }
+
+ return {
+ threadId,
+ createdAt: firstRun.createdAt,
+ lastActivityAt: lastRun.createdAt,
+ isRunning: store.isRunning,
+ messageCount: messageIds.size,
+ firstMessage,
+ resourceId: store.resourceIds[0] || "unknown", // Return first for backward compatibility
+ properties: store.properties,
+ };
+ }
+
+ async deleteThread(threadId: string, scope?: { resourceId: string | string[] } | null): Promise {
+ const store = GLOBAL_STORE.get(threadId);
+ if (!store || !matchesScope(store, scope)) {
+ return;
+ }
+
+ // Abort the agent if running
+ if (store.agent) {
+ try {
+ store.agent.abortRun();
+ } catch (error) {
+ console.warn("Failed to abort agent during thread deletion:", error);
+ }
+ }
+ store.subject?.complete();
+ GLOBAL_STORE.delete(threadId);
+ }
+
+ /**
+ * Clear all threads from the global store (for testing purposes only)
+ * @internal
+ */
+ clearAllThreads(): void {
+ for (const [threadId, store] of GLOBAL_STORE.entries()) {
+ // Abort the agent if running
+ if (store.agent) {
+ try {
+ store.agent.abortRun();
+ } catch (error) {
+ console.warn("Failed to abort agent during clearAllThreads:", error);
+ }
+ }
+ store.subject?.complete();
+ GLOBAL_STORE.delete(threadId);
}
}
}
diff --git a/packages/runtime/src/runtime.ts b/packages/runtime/src/runtime.ts
index deb391f2..4d7bc39b 100644
--- a/packages/runtime/src/runtime.ts
+++ b/packages/runtime/src/runtime.ts
@@ -1,15 +1,13 @@
-import { MaybePromise, NonEmptyRecord } from "@copilotkitnext/shared";
+import { MaybePromise, NonEmptyRecord, logger } from "@copilotkitnext/shared";
import { AbstractAgent } from "@ag-ui/client";
import pkg from "../package.json";
-import type {
- BeforeRequestMiddleware,
- AfterRequestMiddleware,
-} from "./middleware";
+import type { BeforeRequestMiddleware, AfterRequestMiddleware } from "./middleware";
import { TranscriptionService } from "./transcription-service/transcription-service";
-import { AgentRunner } from "./runner/agent-runner";
+import { AgentRunner, ResourceScope } from "./runner/agent-runner";
import { InMemoryAgentRunner } from "./runner/in-memory";
export const VERSION = pkg.version;
+export type { ResourceScope } from "./runner/agent-runner";
/**
* Options used to construct a `CopilotRuntime` instance.
@@ -25,17 +23,127 @@ export interface CopilotRuntimeOptions {
beforeRequestMiddleware?: BeforeRequestMiddleware;
/** Optional *after* middleware – callback function or webhook URL. */
afterRequestMiddleware?: AfterRequestMiddleware;
+ /**
+ * Resolve the resource scope for thread access control.
+ * This is where you authenticate the request and determine which resource(s)
+ * the user has access to.
+ *
+ * If not provided, defaults to GLOBAL_SCOPE (all threads globally accessible).
+ *
+ * Return `null` for admin bypass (no filtering).
+ *
+ * @param context.request - The incoming HTTP request
+ * @param context.clientDeclared - Resource ID(s) the client declares it wants to access (must be validated)
+ *
+ * @example
+ * ```typescript
+ * // Basic usage (determine access from authentication)
+ * resolveThreadsScope: async ({ request }) => {
+ * const user = await authenticate(request);
+ * return { resourceId: user.id };
+ * }
+ *
+ * // Validate client-declared resourceId
+ * resolveThreadsScope: async ({ request, clientDeclared }) => {
+ * const user = await authenticate(request);
+ * if (clientDeclared && clientDeclared !== user.id) {
+ * throw new Error('Unauthorized');
+ * }
+ * return { resourceId: user.id };
+ * }
+ *
+ * // Multi-resource: Filter client-declared IDs to only those user has access to
+ * resolveThreadsScope: async ({ request, clientDeclared }) => {
+ * const user = await authenticate(request);
+ * const userResourceIds = await getUserResourceIds(user);
+ * const requestedIds = Array.isArray(clientDeclared) ? clientDeclared : [clientDeclared];
+ * const allowedIds = requestedIds.filter(id => userResourceIds.includes(id));
+ * return { resourceId: allowedIds };
+ * }
+ * ```
+ */
+ resolveThreadsScope?: (context: {
+ request: Request;
+ clientDeclared?: string | string[];
+ }) => Promise;
+ /**
+ * Suppress warning when using GLOBAL_SCOPE.
+ *
+ * Set to `true` if you intentionally want all threads to be globally accessible
+ * (e.g., single-user apps, demos, prototypes).
+ */
+ suppressResourceIdWarning?: boolean;
}
/**
* Central runtime object passed to all request handlers.
*/
export class CopilotRuntime {
+ /**
+ * Built-in global scope for single-user apps or demos.
+ *
+ * All threads are globally accessible when using this scope.
+ *
+ * @example
+ * ```typescript
+ * new CopilotRuntime({
+ * agents: { myAgent },
+ * resolveThreadsScope: CopilotRuntime.GLOBAL_SCOPE,
+ * suppressResourceIdWarning: true
+ * });
+ * ```
+ */
+ static readonly GLOBAL_SCOPE = async (context: {
+ request: Request;
+ clientDeclared?: string | string[];
+ }): Promise => ({
+ resourceId: "global",
+ });
+
+ /**
+ * Parses the client-declared resource ID(s) from the request header.
+ *
+ * This is a utility method used internally by handlers to extract the
+ * `X-CopilotKit-Resource-ID` header sent by the client via `CopilotKitProvider`.
+ *
+ * **You typically don't need to call this directly** - it's automatically called
+ * by the runtime handlers and passed to your `resolveThreadsScope` function as
+ * the `clientDeclared` parameter.
+ *
+ * @param request - The incoming HTTP request
+ * @returns The parsed resource ID(s), or undefined if header is missing
+ * - Returns a string if single ID
+ * - Returns an array if multiple comma-separated IDs
+ * - Returns undefined if header not present
+ *
+ * @example
+ * ```typescript
+ * // Automatically used internally:
+ * const clientDeclared = CopilotRuntime.parseClientDeclaredResourceId(request);
+ * const scope = await runtime.resolveThreadsScope({ request, clientDeclared });
+ * ```
+ */
+ public static parseClientDeclaredResourceId(request: Request): string | string[] | undefined {
+ const header = request.headers.get("X-CopilotKit-Resource-ID");
+ if (!header) {
+ return undefined;
+ }
+
+ // Parse comma-separated, URI-encoded values
+ const values = header.split(",").map((v) => decodeURIComponent(v.trim()));
+ return values.length === 1 ? values[0] : values;
+ }
+
public agents: CopilotRuntimeOptions["agents"];
public transcriptionService: CopilotRuntimeOptions["transcriptionService"];
public beforeRequestMiddleware: CopilotRuntimeOptions["beforeRequestMiddleware"];
public afterRequestMiddleware: CopilotRuntimeOptions["afterRequestMiddleware"];
public runner: AgentRunner;
+ public resolveThreadsScope: (context: {
+ request: Request;
+ clientDeclared?: string | string[];
+ }) => Promise;
+ private suppressResourceIdWarning: boolean;
constructor({
agents,
@@ -43,11 +151,42 @@ export class CopilotRuntime {
beforeRequestMiddleware,
afterRequestMiddleware,
runner,
+ resolveThreadsScope,
+ suppressResourceIdWarning = false,
}: CopilotRuntimeOptions) {
this.agents = agents;
this.transcriptionService = transcriptionService;
this.beforeRequestMiddleware = beforeRequestMiddleware;
this.afterRequestMiddleware = afterRequestMiddleware;
this.runner = runner ?? new InMemoryAgentRunner();
+ this.resolveThreadsScope = resolveThreadsScope ?? CopilotRuntime.GLOBAL_SCOPE;
+ this.suppressResourceIdWarning = suppressResourceIdWarning;
+
+ // Warn if using GLOBAL_SCOPE without explicit configuration
+ if (!resolveThreadsScope && !suppressResourceIdWarning) {
+ this.logGlobalScopeWarning();
+ }
+ }
+
+ private logGlobalScopeWarning(): void {
+ const isProduction = process.env.NODE_ENV === "production";
+
+ if (isProduction) {
+ logger.error({
+ msg: "CopilotKit Security Warning: GLOBAL_SCOPE in production",
+ details:
+ "No resolveThreadsScope configured. All threads are globally accessible to all users. " +
+ "Configure authentication for production: https://docs.copilotkit.ai/security/thread-scoping " +
+ "To suppress this warning (if intentional), set suppressResourceIdWarning: true",
+ });
+ } else {
+ logger.warn({
+ msg: "CopilotKit: Using GLOBAL_SCOPE",
+ details:
+ "No resolveThreadsScope configured. All threads are globally accessible. " +
+ "This is fine for development, but add authentication for production: " +
+ "https://docs.copilotkit.ai/security/thread-scoping",
+ });
+ }
}
}
diff --git a/packages/shared/src/index.ts b/packages/shared/src/index.ts
index a16bb143..d105c05a 100644
--- a/packages/shared/src/index.ts
+++ b/packages/shared/src/index.ts
@@ -3,6 +3,7 @@ export {
type NonEmptyRecord,
type AgentDescription,
type RuntimeInfo,
+ type ThreadMetadata,
} from "./types";
export * from "./utils";
diff --git a/packages/shared/src/types.ts b/packages/shared/src/types.ts
index 86e429e2..c753dbac 100644
--- a/packages/shared/src/types.ts
+++ b/packages/shared/src/types.ts
@@ -3,12 +3,7 @@ export type MaybePromise = T | PromiseLike;
/**
* More specific utility for records with at least one key
*/
-export type NonEmptyRecord =
- T extends Record
- ? keyof T extends never
- ? never
- : T
- : never;
+export type NonEmptyRecord = T extends Record ? (keyof T extends never ? never : T) : never;
/**
* Type representing an agent's basic information
@@ -24,3 +19,17 @@ export interface RuntimeInfo {
agents: Record;
audioFileTranscriptionEnabled: boolean;
}
+
+/**
+ * Metadata about a conversation thread
+ */
+export interface ThreadMetadata {
+ threadId: string;
+ createdAt: number;
+ lastActivityAt: number;
+ isRunning: boolean;
+ messageCount: number;
+ firstMessage?: string;
+ resourceId?: string;
+ properties?: Record;
+}
diff --git a/packages/sqlite-runner/src/__tests__/resource-scoping.test.ts b/packages/sqlite-runner/src/__tests__/resource-scoping.test.ts
new file mode 100644
index 00000000..faf962e7
--- /dev/null
+++ b/packages/sqlite-runner/src/__tests__/resource-scoping.test.ts
@@ -0,0 +1,547 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { SqliteAgentRunner } from "../sqlite-runner";
+import {
+ AbstractAgent,
+ BaseEvent,
+ RunAgentInput,
+ EventType,
+ Message,
+ TextMessageStartEvent,
+ TextMessageContentEvent,
+ TextMessageEndEvent,
+} from "@ag-ui/client";
+import { EMPTY, firstValueFrom } from "rxjs";
+import { toArray } from "rxjs/operators";
+
+type RunCallbacks = {
+ onEvent: (event: { event: BaseEvent }) => void;
+ onNewMessage?: (args: { message: Message }) => void;
+ onRunStartedEvent?: () => void;
+};
+
+// Mock agent for testing
+class MockAgent extends AbstractAgent {
+ private events: BaseEvent[];
+
+ constructor(events: BaseEvent[] = []) {
+ super();
+ this.events = events;
+ }
+
+ async runAgent(input: RunAgentInput, callbacks: RunCallbacks): Promise {
+ if (callbacks.onRunStartedEvent) {
+ callbacks.onRunStartedEvent();
+ }
+
+ for (const event of this.events) {
+ callbacks.onEvent({ event });
+ }
+ }
+
+ clone(): AbstractAgent {
+ return new MockAgent(this.events);
+ }
+
+ protected run(): ReturnType {
+ return EMPTY;
+ }
+
+ protected connect(): ReturnType {
+ return EMPTY;
+ }
+}
+
+describe("Resource Scoping - SqliteAgentRunner", () => {
+ let runner: SqliteAgentRunner;
+
+ beforeEach(() => {
+ // Use in-memory database for tests
+ runner = new SqliteAgentRunner({ dbPath: ":memory:" });
+ });
+
+ afterEach(() => {
+ runner.close();
+ });
+
+ const createTestEvents = (messageText: string, messageId: string): BaseEvent[] => [
+ { type: EventType.TEXT_MESSAGE_START, messageId, role: "user" } as TextMessageStartEvent,
+ { type: EventType.TEXT_MESSAGE_CONTENT, messageId, delta: messageText } as TextMessageContentEvent,
+ { type: EventType.TEXT_MESSAGE_END, messageId } as TextMessageEndEvent,
+ ];
+
+ describe("Scope Isolation", () => {
+ it("should prevent hijacking existing threads from other users", async () => {
+ const agent = new MockAgent(createTestEvents("Alice's thread", "msg1"));
+
+ // Alice creates a thread
+ const aliceObs = runner.run({
+ threadId: "thread-123",
+ agent,
+ input: { threadId: "thread-123", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "user-alice" },
+ });
+ await firstValueFrom(aliceObs.pipe(toArray()));
+
+ // Bob tries to run on Alice's thread - should be rejected
+ const bobAgent = new MockAgent(createTestEvents("Bob hijacking", "msg2"));
+ expect(() => {
+ runner.run({
+ threadId: "thread-123",
+ agent: bobAgent,
+ input: { threadId: "thread-123", runId: "run-2", messages: [], state: {} },
+ scope: { resourceId: "user-bob" },
+ });
+ }).toThrow("Unauthorized: Cannot run on thread owned by different resource");
+ });
+
+ it("should reject empty resourceId arrays", async () => {
+ const agent = new MockAgent(createTestEvents("Test", "msg1"));
+
+ expect(() => {
+ runner.run({
+ threadId: "thread-empty",
+ agent,
+ input: { threadId: "thread-empty", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: [] },
+ });
+ }).toThrow("Invalid scope: resourceId array cannot be empty");
+ });
+
+ it("should isolate threads by resourceId", async () => {
+ const agent1 = new MockAgent(createTestEvents("User 1 message", "msg1"));
+ const agent2 = new MockAgent(createTestEvents("User 2 message", "msg2"));
+
+ // Create thread for user-1
+ const obs1 = runner.run({
+ threadId: "thread-1",
+ agent: agent1,
+ input: { threadId: "thread-1", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "user-1" },
+ });
+ await firstValueFrom(obs1.pipe(toArray()));
+
+ // Create thread for user-2
+ const obs2 = runner.run({
+ threadId: "thread-2",
+ agent: agent2,
+ input: { threadId: "thread-2", runId: "run-2", messages: [], state: {} },
+ scope: { resourceId: "user-2" },
+ });
+ await firstValueFrom(obs2.pipe(toArray()));
+
+ // User 1 should only see their thread
+ const user1Threads = await runner.listThreads({
+ scope: { resourceId: "user-1" },
+ limit: 10,
+ });
+ expect(user1Threads.threads).toHaveLength(1);
+ expect(user1Threads.threads[0].threadId).toBe("thread-1");
+ expect(user1Threads.threads[0].resourceId).toBe("user-1");
+
+ // User 2 should only see their thread
+ const user2Threads = await runner.listThreads({
+ scope: { resourceId: "user-2" },
+ limit: 10,
+ });
+ expect(user2Threads.threads).toHaveLength(1);
+ expect(user2Threads.threads[0].threadId).toBe("thread-2");
+ expect(user2Threads.threads[0].resourceId).toBe("user-2");
+ });
+
+ it("should return 404-style empty result when accessing another user's thread", async () => {
+ const agent = new MockAgent(createTestEvents("User 1 message", "msg1"));
+
+ // Create thread for user-1
+ const obs = runner.run({
+ threadId: "thread-user1",
+ agent,
+ input: { threadId: "thread-user1", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "user-1" },
+ });
+ await firstValueFrom(obs.pipe(toArray()));
+
+ // User 2 attempts to connect to user 1's thread - should get empty (404)
+ const connectObs = runner.connect({
+ threadId: "thread-user1",
+ scope: { resourceId: "user-2" },
+ });
+
+ const events = await firstValueFrom(connectObs.pipe(toArray()));
+ expect(events).toEqual([]);
+ });
+
+ it("should return null when getting metadata for another user's thread", async () => {
+ const agent = new MockAgent(createTestEvents("User 1 message", "msg1"));
+
+ // Create thread for user-1
+ const obs = runner.run({
+ threadId: "thread-user1",
+ agent,
+ input: { threadId: "thread-user1", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "user-1" },
+ });
+ await firstValueFrom(obs.pipe(toArray()));
+
+ // User 2 attempts to get metadata - should return null (404)
+ const metadata = await runner.getThreadMetadata("thread-user1", { resourceId: "user-2" });
+ expect(metadata).toBeNull();
+ });
+
+ it("should silently succeed when deleting another user's thread (idempotent)", async () => {
+ const agent = new MockAgent(createTestEvents("User 1 message", "msg1"));
+
+ // Create thread for user-1
+ const obs = runner.run({
+ threadId: "thread-user1",
+ agent,
+ input: { threadId: "thread-user1", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "user-1" },
+ });
+ await firstValueFrom(obs.pipe(toArray()));
+
+ // User 2 attempts to delete user 1's thread - should silently succeed
+ await expect(
+ runner.deleteThread("thread-user1", { resourceId: "user-2" })
+ ).resolves.toBeUndefined();
+
+ // Verify thread still exists for user 1
+ const metadata = await runner.getThreadMetadata("thread-user1", { resourceId: "user-1" });
+ expect(metadata).not.toBeNull();
+ });
+ });
+
+ describe("Multi-Resource Access (Array Queries)", () => {
+ it("should allow access to threads from multiple resourceIds", async () => {
+ const agent = new MockAgent(createTestEvents("Test message", "msg1"));
+
+ // Create thread in personal workspace
+ const obs1 = runner.run({
+ threadId: "thread-personal",
+ agent,
+ input: { threadId: "thread-personal", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "user-1-personal" },
+ });
+ await firstValueFrom(obs1.pipe(toArray()));
+
+ // Create thread in team workspace
+ const obs2 = runner.run({
+ threadId: "thread-team",
+ agent,
+ input: { threadId: "thread-team", runId: "run-2", messages: [], state: {} },
+ scope: { resourceId: "workspace-123" },
+ });
+ await firstValueFrom(obs2.pipe(toArray()));
+
+ // Create thread for another user
+ const obs3 = runner.run({
+ threadId: "thread-other",
+ agent,
+ input: { threadId: "thread-other", runId: "run-3", messages: [], state: {} },
+ scope: { resourceId: "user-2-personal" },
+ });
+ await firstValueFrom(obs3.pipe(toArray()));
+
+ // User with access to both personal and team workspace
+ const threads = await runner.listThreads({
+ scope: { resourceId: ["user-1-personal", "workspace-123"] },
+ limit: 10,
+ });
+
+ // Should see both personal and team threads, but not other user's thread
+ expect(threads.threads).toHaveLength(2);
+ const threadIds = threads.threads.map((t) => t.threadId).sort();
+ expect(threadIds).toEqual(["thread-personal", "thread-team"]);
+ });
+
+ it("should allow connecting to thread from any resourceId in array", async () => {
+ const agent = new MockAgent(createTestEvents("Workspace message", "msg1"));
+
+ // Create thread in workspace
+ const obs = runner.run({
+ threadId: "thread-workspace",
+ agent,
+ input: { threadId: "thread-workspace", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "workspace-456" },
+ });
+ await firstValueFrom(obs.pipe(toArray()));
+
+ // User with access to multiple workspaces should be able to connect
+ const connectObs = runner.connect({
+ threadId: "thread-workspace",
+ scope: { resourceId: ["user-1-personal", "workspace-456", "workspace-789"] },
+ });
+
+ const events = await firstValueFrom(connectObs.pipe(toArray()));
+ expect(events.length).toBeGreaterThan(0);
+ });
+
+ it("should get metadata for thread with multi-resource scope", async () => {
+ const agent = new MockAgent(createTestEvents("Team thread", "msg1"));
+
+ // Create thread in team workspace
+ const obs = runner.run({
+ threadId: "thread-team",
+ agent,
+ input: { threadId: "thread-team", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "workspace-999" },
+ });
+ await firstValueFrom(obs.pipe(toArray()));
+
+ // User with array scope including this workspace
+ const metadata = await runner.getThreadMetadata("thread-team", {
+ resourceId: ["user-1-personal", "workspace-999"],
+ });
+
+ expect(metadata).not.toBeNull();
+ expect(metadata!.threadId).toBe("thread-team");
+ expect(metadata!.resourceId).toBe("workspace-999");
+ });
+
+ it("should return null for metadata when resourceId not in array", async () => {
+ const agent = new MockAgent(createTestEvents("Private thread", "msg1"));
+
+ // Create thread in workspace
+ const obs = runner.run({
+ threadId: "thread-private",
+ agent,
+ input: { threadId: "thread-private", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "workspace-secret" },
+ });
+ await firstValueFrom(obs.pipe(toArray()));
+
+ // User with different workspaces
+ const metadata = await runner.getThreadMetadata("thread-private", {
+ resourceId: ["workspace-1", "workspace-2"],
+ });
+
+ expect(metadata).toBeNull();
+ });
+
+ it("should handle empty array gracefully", async () => {
+ const agent = new MockAgent(createTestEvents("Test", "msg1"));
+
+ const obs = runner.run({
+ threadId: "thread-1",
+ agent,
+ input: { threadId: "thread-1", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "user-1" },
+ });
+ await firstValueFrom(obs.pipe(toArray()));
+
+ // Empty array should not match anything
+ const threads = await runner.listThreads({
+ scope: { resourceId: [] },
+ limit: 10,
+ });
+
+ expect(threads.threads).toHaveLength(0);
+ });
+ });
+
+ describe("Admin Bypass (Null Scope)", () => {
+ it("should list all threads when scope is null", async () => {
+ const agent = new MockAgent(createTestEvents("Test message", "msg1"));
+
+ // Create threads for different users
+ const obs1 = runner.run({
+ threadId: "thread-user1",
+ agent,
+ input: { threadId: "thread-user1", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "user-1" },
+ });
+ await firstValueFrom(obs1.pipe(toArray()));
+
+ const obs2 = runner.run({
+ threadId: "thread-user2",
+ agent,
+ input: { threadId: "thread-user2", runId: "run-2", messages: [], state: {} },
+ scope: { resourceId: "user-2" },
+ });
+ await firstValueFrom(obs2.pipe(toArray()));
+
+ const obs3 = runner.run({
+ threadId: "thread-user3",
+ agent,
+ input: { threadId: "thread-user3", runId: "run-3", messages: [], state: {} },
+ scope: { resourceId: "user-3" },
+ });
+ await firstValueFrom(obs3.pipe(toArray()));
+
+ // Admin with null scope should see all threads
+ const adminThreads = await runner.listThreads({
+ scope: null,
+ limit: 10,
+ });
+
+ expect(adminThreads.threads).toHaveLength(3);
+ const threadIds = adminThreads.threads.map((t) => t.threadId).sort();
+ expect(threadIds).toEqual(["thread-user1", "thread-user2", "thread-user3"]);
+ });
+
+ it("should get metadata for any thread when scope is null", async () => {
+ const agent = new MockAgent(createTestEvents("User thread", "msg1"));
+
+ // Create thread for user-1
+ const obs = runner.run({
+ threadId: "thread-user1",
+ agent,
+ input: { threadId: "thread-user1", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "user-1" },
+ });
+ await firstValueFrom(obs.pipe(toArray()));
+
+ // Admin should be able to get metadata
+ const metadata = await runner.getThreadMetadata("thread-user1", null);
+
+ expect(metadata).not.toBeNull();
+ expect(metadata!.threadId).toBe("thread-user1");
+ expect(metadata!.resourceId).toBe("user-1");
+ });
+
+ it("should delete any thread when scope is null", async () => {
+ const agent = new MockAgent(createTestEvents("User thread", "msg1"));
+
+ // Create thread for user-1
+ const obs = runner.run({
+ threadId: "thread-user1",
+ agent,
+ input: { threadId: "thread-user1", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "user-1" },
+ });
+ await firstValueFrom(obs.pipe(toArray()));
+
+ // Admin deletes thread
+ await runner.deleteThread("thread-user1", null);
+
+ // Verify thread is deleted even for the owner
+ const metadata = await runner.getThreadMetadata("thread-user1", { resourceId: "user-1" });
+ expect(metadata).toBeNull();
+ });
+
+ it("should connect to any thread when scope is null", async () => {
+ const agent = new MockAgent(createTestEvents("User message", "msg1"));
+
+ // Create thread for user-1
+ const obs = runner.run({
+ threadId: "thread-user1",
+ agent,
+ input: { threadId: "thread-user1", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "user-1" },
+ });
+ await firstValueFrom(obs.pipe(toArray()));
+
+ // Admin connects with null scope
+ const connectObs = runner.connect({
+ threadId: "thread-user1",
+ scope: null,
+ });
+
+ const events = await firstValueFrom(connectObs.pipe(toArray()));
+ expect(events.length).toBeGreaterThan(0);
+ });
+ });
+
+ describe("Properties Field", () => {
+ it("should store and retrieve properties", async () => {
+ const agent = new MockAgent(createTestEvents("Test message", "msg1"));
+
+ // Create thread with properties
+ const obs = runner.run({
+ threadId: "thread-with-props",
+ agent,
+ input: { threadId: "thread-with-props", runId: "run-1", messages: [], state: {} },
+ scope: {
+ resourceId: "user-1",
+ properties: { organizationId: "org-123", department: "engineering" },
+ },
+ });
+ await firstValueFrom(obs.pipe(toArray()));
+
+ // Get metadata and verify properties
+ const metadata = await runner.getThreadMetadata("thread-with-props", { resourceId: "user-1" });
+
+ expect(metadata).not.toBeNull();
+ expect(metadata!.properties).toEqual({
+ organizationId: "org-123",
+ department: "engineering",
+ });
+ });
+
+ it("should handle undefined properties", async () => {
+ const agent = new MockAgent(createTestEvents("Test message", "msg1"));
+
+ // Create thread without properties
+ const obs = runner.run({
+ threadId: "thread-no-props",
+ agent,
+ input: { threadId: "thread-no-props", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "user-1" },
+ });
+ await firstValueFrom(obs.pipe(toArray()));
+
+ // Get metadata and verify properties is undefined
+ const metadata = await runner.getThreadMetadata("thread-no-props", { resourceId: "user-1" });
+
+ expect(metadata).not.toBeNull();
+ expect(metadata!.properties).toBeUndefined();
+ });
+
+ it("should include properties in list results", async () => {
+ const agent = new MockAgent(createTestEvents("Test message", "msg1"));
+
+ // Create thread with properties
+ const obs = runner.run({
+ threadId: "thread-1",
+ agent,
+ input: { threadId: "thread-1", runId: "run-1", messages: [], state: {} },
+ scope: {
+ resourceId: "user-1",
+ properties: { tier: "premium", region: "us-east" },
+ },
+ });
+ await firstValueFrom(obs.pipe(toArray()));
+
+ // List threads
+ const threads = await runner.listThreads({
+ scope: { resourceId: "user-1" },
+ limit: 10,
+ });
+
+ expect(threads.threads).toHaveLength(1);
+ expect(threads.threads[0].properties).toEqual({
+ tier: "premium",
+ region: "us-east",
+ });
+ });
+ });
+
+ describe("Database Persistence", () => {
+ it("should persist scope across runner instances", async () => {
+ const agent = new MockAgent(createTestEvents("Persistent message", "msg1"));
+
+ // Create runner with file-based database
+ const tempDb = ":memory:"; // In real test could use temp file
+ const runner1 = new SqliteAgentRunner({ dbPath: tempDb });
+
+ // Create thread
+ const obs = runner1.run({
+ threadId: "thread-persist",
+ agent,
+ input: { threadId: "thread-persist", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "user-persist", properties: { test: "value" } },
+ });
+ await firstValueFrom(obs.pipe(toArray()));
+
+ // Query in same instance
+ const metadata1 = await runner1.getThreadMetadata("thread-persist", {
+ resourceId: "user-persist",
+ });
+
+ expect(metadata1).not.toBeNull();
+ expect(metadata1!.resourceId).toBe("user-persist");
+ expect(metadata1!.properties).toEqual({ test: "value" });
+
+ runner1.close();
+ });
+ });
+});
diff --git a/packages/sqlite-runner/src/__tests__/thread-hijacking.test.ts b/packages/sqlite-runner/src/__tests__/thread-hijacking.test.ts
new file mode 100644
index 00000000..eaaa9479
--- /dev/null
+++ b/packages/sqlite-runner/src/__tests__/thread-hijacking.test.ts
@@ -0,0 +1,548 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { SqliteAgentRunner } from "../sqlite-runner";
+import {
+ AbstractAgent,
+ BaseEvent,
+ RunAgentInput,
+ EventType,
+ TextMessageStartEvent,
+ TextMessageContentEvent,
+ TextMessageEndEvent,
+ Message,
+} from "@ag-ui/client";
+import { EMPTY, firstValueFrom } from "rxjs";
+import { toArray } from "rxjs/operators";
+
+type RunCallbacks = {
+ onEvent: (event: { event: BaseEvent }) => void;
+ onNewMessage?: (args: { message: Message }) => void;
+ onRunStartedEvent?: () => void;
+};
+
+class MockAgent extends AbstractAgent {
+ private events: BaseEvent[];
+
+ constructor(events: BaseEvent[] = []) {
+ super();
+ this.events = events;
+ }
+
+ async runAgent(input: RunAgentInput, callbacks: RunCallbacks): Promise {
+ if (callbacks.onRunStartedEvent) {
+ callbacks.onRunStartedEvent();
+ }
+
+ for (const event of this.events) {
+ callbacks.onEvent({ event });
+ }
+ }
+
+ clone(): AbstractAgent {
+ return new MockAgent(this.events);
+ }
+
+ protected run(): ReturnType {
+ return EMPTY;
+ }
+
+ protected connect(): ReturnType {
+ return EMPTY;
+ }
+}
+
+describe("Thread Hijacking Prevention - SqliteAgentRunner", () => {
+ let runner: SqliteAgentRunner;
+
+ beforeEach(() => {
+ runner = new SqliteAgentRunner({ dbPath: ":memory:" });
+ });
+
+ afterEach(() => {
+ runner.close();
+ });
+
+ const createTestEvents = (text: string, id: string): BaseEvent[] => [
+ { type: EventType.TEXT_MESSAGE_START, messageId: id, role: "user" } as TextMessageStartEvent,
+ { type: EventType.TEXT_MESSAGE_CONTENT, messageId: id, delta: text } as TextMessageContentEvent,
+ { type: EventType.TEXT_MESSAGE_END, messageId: id } as TextMessageEndEvent,
+ ];
+
+ describe("Basic Hijacking Attempts", () => {
+ it("should reject attempts to run on another user's thread", async () => {
+ const agent = new MockAgent(createTestEvents("Alice's message", "msg1"));
+
+ // Alice creates a thread
+ const aliceObs = runner.run({
+ threadId: "shared-thread-123",
+ agent,
+ input: { threadId: "shared-thread-123", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "user-alice" },
+ });
+ await firstValueFrom(aliceObs.pipe(toArray()));
+
+ // Bob tries to hijack Alice's thread
+ const bobAgent = new MockAgent(createTestEvents("Bob's hijack attempt", "msg2"));
+
+ expect(() => {
+ runner.run({
+ threadId: "shared-thread-123",
+ agent: bobAgent,
+ input: { threadId: "shared-thread-123", runId: "run-2", messages: [], state: {} },
+ scope: { resourceId: "user-bob" },
+ });
+ }).toThrow("Unauthorized: Cannot run on thread owned by different resource");
+
+ // Verify Alice's thread is untouched
+ const aliceThreads = await runner.listThreads({
+ scope: { resourceId: "user-alice" },
+ limit: 10,
+ });
+ expect(aliceThreads.threads).toHaveLength(1);
+ expect(aliceThreads.threads[0].threadId).toBe("shared-thread-123");
+ });
+
+ it("should allow legitimate user to continue their own thread", async () => {
+ const agent1 = new MockAgent(createTestEvents("Message 1", "msg1"));
+ const agent2 = new MockAgent(createTestEvents("Message 2", "msg2"));
+
+ // Alice creates a thread
+ const obs1 = runner.run({
+ threadId: "alice-thread",
+ agent: agent1,
+ input: { threadId: "alice-thread", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "user-alice" },
+ });
+ await firstValueFrom(obs1.pipe(toArray()));
+
+ // Alice continues her own thread - should work
+ const obs2 = runner.run({
+ threadId: "alice-thread",
+ agent: agent2,
+ input: { threadId: "alice-thread", runId: "run-2", messages: [], state: {} },
+ scope: { resourceId: "user-alice" },
+ });
+
+ const events = await firstValueFrom(obs2.pipe(toArray()));
+ expect(events.length).toBeGreaterThan(0);
+ });
+
+ it("should prevent hijacking with similar but different resourceIds", async () => {
+ const agent = new MockAgent(createTestEvents("Test", "msg1"));
+
+ // User alice creates thread
+ const obs1 = runner.run({
+ threadId: "thread-xyz",
+ agent,
+ input: { threadId: "thread-xyz", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "user-alice" },
+ });
+ await firstValueFrom(obs1.pipe(toArray()));
+
+ // User alice2 tries to hijack (similar name)
+ expect(() => {
+ runner.run({
+ threadId: "thread-xyz",
+ agent,
+ input: { threadId: "thread-xyz", runId: "run-2", messages: [], state: {} },
+ scope: { resourceId: "user-alice2" },
+ });
+ }).toThrow("Unauthorized");
+ });
+ });
+
+ describe("Multi-Resource Access", () => {
+ it("should allow access if user has thread's resourceId in array", async () => {
+ const agent1 = new MockAgent(createTestEvents("Workspace message", "msg1"));
+ const agent2 = new MockAgent(createTestEvents("Follow-up", "msg2"));
+
+ // Create thread in workspace
+ const obs1 = runner.run({
+ threadId: "workspace-thread",
+ agent: agent1,
+ input: { threadId: "workspace-thread", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "workspace-123" },
+ });
+ await firstValueFrom(obs1.pipe(toArray()));
+
+ // User with multi-resource access (personal + workspace)
+ const obs2 = runner.run({
+ threadId: "workspace-thread",
+ agent: agent2,
+ input: { threadId: "workspace-thread", runId: "run-2", messages: [], state: {} },
+ scope: { resourceId: ["user-alice", "workspace-123"] },
+ });
+
+ const events = await firstValueFrom(obs2.pipe(toArray()));
+ expect(events.length).toBeGreaterThan(0);
+ });
+
+ it("should reject if thread's resourceId is not in user's array", async () => {
+ const agent = new MockAgent(createTestEvents("Test", "msg1"));
+
+ // Create thread in workspace-A
+ const obs1 = runner.run({
+ threadId: "thread-a",
+ agent,
+ input: { threadId: "thread-a", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "workspace-a" },
+ });
+ await firstValueFrom(obs1.pipe(toArray()));
+
+ // User with access to workspace-B and workspace-C only
+ expect(() => {
+ runner.run({
+ threadId: "thread-a",
+ agent,
+ input: { threadId: "thread-a", runId: "run-2", messages: [], state: {} },
+ scope: { resourceId: ["workspace-b", "workspace-c"] },
+ });
+ }).toThrow("Unauthorized");
+ });
+ });
+
+ describe("Admin Bypass", () => {
+ it("should allow admin (null scope) to run on existing threads", async () => {
+ const agent1 = new MockAgent(createTestEvents("User message", "msg1"));
+ const agent2 = new MockAgent(createTestEvents("Admin reply", "msg2"));
+
+ // Regular user creates thread
+ const obs1 = runner.run({
+ threadId: "user-thread",
+ agent: agent1,
+ input: { threadId: "user-thread", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "user-alice" },
+ });
+ await firstValueFrom(obs1.pipe(toArray()));
+
+ // Admin runs on user's thread with null scope
+ const obs2 = runner.run({
+ threadId: "user-thread",
+ agent: agent2,
+ input: { threadId: "user-thread", runId: "run-2", messages: [], state: {} },
+ scope: null,
+ });
+
+ const events = await firstValueFrom(obs2.pipe(toArray()));
+ expect(events.length).toBeGreaterThan(0);
+ });
+
+ it("should reject admin attempts to create threads with null scope", () => {
+ const agent = new MockAgent(createTestEvents("Admin thread", "msg1"));
+
+ // Admin tries to create thread with null scope - should be rejected
+ expect(() => {
+ runner.run({
+ threadId: "admin-thread",
+ agent,
+ input: { threadId: "admin-thread", runId: "run-1", messages: [], state: {} },
+ scope: null,
+ });
+ }).toThrow("Cannot create thread with null scope");
+ });
+
+ it("should allow admin to list all threads with null scope", async () => {
+ const agent = new MockAgent(createTestEvents("Test", "msg1"));
+
+ // Create threads for different users
+ await firstValueFrom(
+ runner.run({
+ threadId: "alice-thread",
+ agent,
+ input: { threadId: "alice-thread", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "user-alice" },
+ }).pipe(toArray())
+ );
+
+ await firstValueFrom(
+ runner.run({
+ threadId: "bob-thread",
+ agent,
+ input: { threadId: "bob-thread", runId: "run-2", messages: [], state: {} },
+ scope: { resourceId: "user-bob" },
+ }).pipe(toArray())
+ );
+
+ // Admin can see all threads
+ const allThreads = await runner.listThreads({
+ scope: null,
+ limit: 10,
+ });
+ expect(allThreads.threads).toHaveLength(2);
+ });
+ });
+
+ describe("Empty Array Validation", () => {
+ it("should reject empty resourceId array on new thread", () => {
+ const agent = new MockAgent(createTestEvents("Test", "msg1"));
+
+ expect(() => {
+ runner.run({
+ threadId: "new-thread",
+ agent,
+ input: { threadId: "new-thread", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: [] },
+ });
+ }).toThrow("Invalid scope: resourceId array cannot be empty");
+ });
+
+ it("should reject empty resourceId array on existing thread", async () => {
+ const agent = new MockAgent(createTestEvents("Test", "msg1"));
+
+ // Create thread with valid scope
+ const obs1 = runner.run({
+ threadId: "thread-1",
+ agent,
+ input: { threadId: "thread-1", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "user-alice" },
+ });
+ await firstValueFrom(obs1.pipe(toArray()));
+
+ // Try to run with empty array
+ expect(() => {
+ runner.run({
+ threadId: "thread-1",
+ agent,
+ input: { threadId: "thread-1", runId: "run-2", messages: [], state: {} },
+ scope: { resourceId: [] },
+ });
+ }).toThrow("Invalid scope: resourceId array cannot be empty");
+ });
+ });
+
+ describe("Race Conditions", () => {
+ it("should prevent concurrent hijacking attempts", async () => {
+ const agent = new MockAgent(createTestEvents("Test", "msg1"));
+
+ // Alice creates thread
+ const obs1 = runner.run({
+ threadId: "race-thread",
+ agent,
+ input: { threadId: "race-thread", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "user-alice" },
+ });
+ await firstValueFrom(obs1.pipe(toArray()));
+
+ // Multiple users try to hijack simultaneously
+ const attempts = ["bob", "charlie", "dave"].map((user) => {
+ return new Promise((resolve) => {
+ try {
+ runner.run({
+ threadId: "race-thread",
+ agent,
+ input: { threadId: "race-thread", runId: `run-${user}`, messages: [], state: {} },
+ scope: { resourceId: `user-${user}` },
+ });
+ resolve({ user, success: true });
+ } catch (error) {
+ resolve({ user, success: false, error: (error as Error).message });
+ }
+ });
+ });
+
+ const results = await Promise.all(attempts);
+
+ // All hijacking attempts should fail
+ results.forEach((result: any) => {
+ expect(result.success).toBe(false);
+ expect(result.error).toContain("Unauthorized");
+ });
+ });
+ });
+
+ describe("Properties Preservation", () => {
+ it("should not overwrite thread properties during hijacking attempt", async () => {
+ const agent = new MockAgent(createTestEvents("Test", "msg1"));
+
+ // Alice creates thread with properties
+ const obs1 = runner.run({
+ threadId: "prop-thread",
+ agent,
+ input: { threadId: "prop-thread", runId: "run-1", messages: [], state: {} },
+ scope: {
+ resourceId: "user-alice",
+ properties: { department: "engineering", tier: "premium" },
+ },
+ });
+ await firstValueFrom(obs1.pipe(toArray()));
+
+ // Bob tries to hijack and overwrite properties
+ try {
+ runner.run({
+ threadId: "prop-thread",
+ agent,
+ input: { threadId: "prop-thread", runId: "run-2", messages: [], state: {} },
+ scope: {
+ resourceId: "user-bob",
+ properties: { department: "sales", tier: "free" },
+ },
+ });
+ } catch {
+ // Expected to fail
+ }
+
+ // Verify original properties are preserved
+ const metadata = await runner.getThreadMetadata("prop-thread", { resourceId: "user-alice" });
+ expect(metadata?.properties).toEqual({
+ department: "engineering",
+ tier: "premium",
+ });
+ });
+ });
+
+ describe("Multi-Resource Thread Persistence", () => {
+ it("should persist all resource IDs from array on thread creation", async () => {
+ const agent = new MockAgent(createTestEvents("Multi-resource message", "msg1"));
+
+ // Create thread with multiple resource IDs
+ await firstValueFrom(
+ runner.run({
+ threadId: "multi-resource-thread",
+ agent,
+ input: { threadId: "multi-resource-thread", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: ["user-123", "workspace-456"] },
+ }).pipe(toArray())
+ );
+
+ // User should be able to access it
+ const userMetadata = await runner.getThreadMetadata("multi-resource-thread", {
+ resourceId: "user-123",
+ });
+ expect(userMetadata).not.toBeNull();
+
+ // Workspace should also be able to access it
+ const workspaceMetadata = await runner.getThreadMetadata("multi-resource-thread", {
+ resourceId: "workspace-456",
+ });
+ expect(workspaceMetadata).not.toBeNull();
+
+ // Unrelated resource should not access it
+ const otherMetadata = await runner.getThreadMetadata("multi-resource-thread", {
+ resourceId: "workspace-789",
+ });
+ expect(otherMetadata).toBeNull();
+ });
+
+ it("should allow any resource owner to continue the thread", async () => {
+ const agent1 = new MockAgent(createTestEvents("First message", "msg1"));
+ const agent2 = new MockAgent(createTestEvents("Second message", "msg2"));
+ const agent3 = new MockAgent(createTestEvents("Third message", "msg3"));
+
+ // Create thread with multiple resource IDs
+ await firstValueFrom(
+ runner.run({
+ threadId: "shared-thread",
+ agent: agent1,
+ input: { threadId: "shared-thread", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: ["user-123", "workspace-456"] },
+ }).pipe(toArray())
+ );
+
+ // User can continue
+ const userEvents = await firstValueFrom(
+ runner.run({
+ threadId: "shared-thread",
+ agent: agent2,
+ input: { threadId: "shared-thread", runId: "run-2", messages: [], state: {} },
+ scope: { resourceId: "user-123" },
+ }).pipe(toArray())
+ );
+ expect(userEvents.length).toBeGreaterThan(0);
+
+ // Workspace can also continue
+ const workspaceEvents = await firstValueFrom(
+ runner.run({
+ threadId: "shared-thread",
+ agent: agent3,
+ input: { threadId: "shared-thread", runId: "run-3", messages: [], state: {} },
+ scope: { resourceId: "workspace-456" },
+ }).pipe(toArray())
+ );
+ expect(workspaceEvents.length).toBeGreaterThan(0);
+ });
+
+ it("should list thread for any of its resource owners", async () => {
+ const agent = new MockAgent(createTestEvents("Shared content", "msg1"));
+
+ // Create thread owned by both user and workspace
+ await firstValueFrom(
+ runner.run({
+ threadId: "listed-thread",
+ agent,
+ input: { threadId: "listed-thread", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: ["user-alice", "workspace-eng"] },
+ }).pipe(toArray())
+ );
+
+ // User can see it in their list
+ const userThreads = await runner.listThreads({
+ scope: { resourceId: "user-alice" },
+ limit: 10,
+ });
+ expect(userThreads.threads.some(t => t.threadId === "listed-thread")).toBe(true);
+
+ // Workspace can see it in their list
+ const workspaceThreads = await runner.listThreads({
+ scope: { resourceId: "workspace-eng" },
+ limit: 10,
+ });
+ expect(workspaceThreads.threads.some(t => t.threadId === "listed-thread")).toBe(true);
+
+ // Other workspace cannot see it
+ const otherThreads = await runner.listThreads({
+ scope: { resourceId: "workspace-sales" },
+ limit: 10,
+ });
+ expect(otherThreads.threads.some(t => t.threadId === "listed-thread")).toBe(false);
+ });
+
+ it("should prevent hijacking of multi-resource threads", async () => {
+ const agent = new MockAgent(createTestEvents("Test", "msg1"));
+
+ // Create thread owned by user and workspace
+ await firstValueFrom(
+ runner.run({
+ threadId: "protected-multi-thread",
+ agent,
+ input: { threadId: "protected-multi-thread", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: ["user-alice", "workspace-eng"] },
+ }).pipe(toArray())
+ );
+
+ // Bob tries to hijack - should fail
+ expect(() => {
+ runner.run({
+ threadId: "protected-multi-thread",
+ agent,
+ input: { threadId: "protected-multi-thread", runId: "run-2", messages: [], state: {} },
+ scope: { resourceId: "user-bob" },
+ });
+ }).toThrow("Unauthorized");
+ });
+
+ it("should allow querying with multi-resource scope", async () => {
+ const agent = new MockAgent(createTestEvents("Test", "msg1"));
+
+ // User with access to multiple workspaces creates thread in one
+ await firstValueFrom(
+ runner.run({
+ threadId: "workspace-a-thread",
+ agent,
+ input: { threadId: "workspace-a-thread", runId: "run-1", messages: [], state: {} },
+ scope: { resourceId: "workspace-a" },
+ }).pipe(toArray())
+ );
+
+ // Query with multiple workspace IDs should find it
+ const metadata = await runner.getThreadMetadata("workspace-a-thread", {
+ resourceId: ["workspace-a", "workspace-b", "workspace-c"],
+ });
+ expect(metadata).not.toBeNull();
+
+ // Query without the matching ID should not find it
+ const noMatch = await runner.getThreadMetadata("workspace-a-thread", {
+ resourceId: ["workspace-b", "workspace-c"],
+ });
+ expect(noMatch).toBeNull();
+ });
+ });
+});
diff --git a/packages/sqlite-runner/src/__tests__/thread-listing.test.ts b/packages/sqlite-runner/src/__tests__/thread-listing.test.ts
new file mode 100644
index 00000000..6427e4d4
--- /dev/null
+++ b/packages/sqlite-runner/src/__tests__/thread-listing.test.ts
@@ -0,0 +1,255 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { SqliteAgentRunner } from "../sqlite-runner";
+import {
+ AbstractAgent,
+ BaseEvent,
+ RunAgentInput,
+ EventType,
+ Message,
+ TextMessageStartEvent,
+ TextMessageContentEvent,
+ TextMessageEndEvent,
+} from "@ag-ui/client";
+import { EMPTY, firstValueFrom } from "rxjs";
+import { toArray } from "rxjs/operators";
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+
+type RunCallbacks = {
+ onEvent: (event: { event: BaseEvent }) => void;
+ onNewMessage?: (args: { message: Message }) => void;
+ onRunStartedEvent?: () => void;
+};
+
+// Mock agent for testing
+class MockAgent extends AbstractAgent {
+ private events: BaseEvent[];
+
+ constructor(events: BaseEvent[] = []) {
+ super();
+ this.events = events;
+ }
+
+ async runAgent(input: RunAgentInput, callbacks: RunCallbacks): Promise {
+ if (callbacks.onRunStartedEvent) {
+ callbacks.onRunStartedEvent();
+ }
+
+ for (const event of this.events) {
+ callbacks.onEvent({ event });
+ }
+ }
+
+ clone(): AbstractAgent {
+ return new MockAgent(this.events);
+ }
+
+ protected run(): ReturnType {
+ return EMPTY;
+ }
+
+ protected connect(): ReturnType {
+ return EMPTY;
+ }
+}
+
+describe("Thread Listing - SqliteAgentRunner", () => {
+ let tempDir: string;
+ let dbPath: string;
+ let runner: SqliteAgentRunner;
+
+ beforeEach(() => {
+ tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "thread-test-"));
+ dbPath = path.join(tempDir, "test.db");
+ runner = new SqliteAgentRunner({ dbPath });
+ });
+
+ afterEach(() => {
+ runner.close();
+ if (fs.existsSync(dbPath)) {
+ fs.unlinkSync(dbPath);
+ }
+ if (fs.existsSync(tempDir)) {
+ fs.rmdirSync(tempDir);
+ }
+ });
+
+ it("should return empty list when no threads exist", async () => {
+ const result = await runner.listThreads({ limit: 10 });
+
+ expect(result.threads).toEqual([]);
+ expect(result.total).toBe(0);
+ });
+
+ it("should list threads after runs are created", async () => {
+ const events: BaseEvent[] = [
+ { type: EventType.TEXT_MESSAGE_START, messageId: "msg1", role: "user" } as TextMessageStartEvent,
+ { type: EventType.TEXT_MESSAGE_CONTENT, messageId: "msg1", delta: "Hello World" } as TextMessageContentEvent,
+ { type: EventType.TEXT_MESSAGE_END, messageId: "msg1" } as TextMessageEndEvent,
+ ];
+
+ const agent = new MockAgent(events);
+
+ // Create first thread
+ const observable1 = runner.run({
+ threadId: "thread-1",
+ agent,
+ input: { threadId: "thread-1", runId: "run-1", messages: [], state: {} },
+ });
+ await firstValueFrom(observable1.pipe(toArray()));
+
+ // Create second thread
+ const observable2 = runner.run({
+ threadId: "thread-2",
+ agent,
+ input: { threadId: "thread-2", runId: "run-2", messages: [], state: {} },
+ });
+ await firstValueFrom(observable2.pipe(toArray()));
+
+ const result = await runner.listThreads({ limit: 10 });
+
+ expect(result.threads).toHaveLength(2);
+ expect(result.total).toBe(2);
+ expect(result.threads.map((t) => t.threadId).sort()).toEqual(["thread-1", "thread-2"]);
+ });
+
+ it("should include thread metadata", async () => {
+ const events: BaseEvent[] = [
+ { type: EventType.TEXT_MESSAGE_START, messageId: "msg1", role: "user" } as TextMessageStartEvent,
+ { type: EventType.TEXT_MESSAGE_CONTENT, messageId: "msg1", delta: "Test message" } as TextMessageContentEvent,
+ { type: EventType.TEXT_MESSAGE_END, messageId: "msg1" } as TextMessageEndEvent,
+ ];
+
+ const agent = new MockAgent(events);
+ const observable = runner.run({
+ threadId: "thread-1",
+ agent,
+ input: { threadId: "thread-1", runId: "run-1", messages: [], state: {} },
+ });
+ await firstValueFrom(observable.pipe(toArray()));
+
+ const result = await runner.listThreads({ limit: 10 });
+ const thread = result.threads[0];
+
+ expect(thread).toBeDefined();
+ expect(thread.threadId).toBe("thread-1");
+ expect(thread.createdAt).toBeGreaterThan(0);
+ expect(thread.lastActivityAt).toBeGreaterThan(0);
+ expect(thread.isRunning).toBe(false);
+ expect(thread.messageCount).toBeGreaterThanOrEqual(1);
+ expect(thread.firstMessage).toBe("Test message");
+ });
+
+ it("should respect limit parameter", async () => {
+ const events: BaseEvent[] = [
+ { type: EventType.TEXT_MESSAGE_START, messageId: "msg1", role: "user" } as TextMessageStartEvent,
+ { type: EventType.TEXT_MESSAGE_CONTENT, messageId: "msg1", delta: "Hello" } as TextMessageContentEvent,
+ { type: EventType.TEXT_MESSAGE_END, messageId: "msg1" } as TextMessageEndEvent,
+ ];
+
+ const agent = new MockAgent(events);
+
+ // Create 5 threads
+ for (let i = 0; i < 5; i++) {
+ const observable = runner.run({
+ threadId: `thread-${i}`,
+ agent,
+ input: { threadId: `thread-${i}`, runId: `run-${i}`, messages: [], state: {} },
+ });
+ await firstValueFrom(observable.pipe(toArray()));
+ }
+
+ const result = await runner.listThreads({ limit: 3 });
+
+ expect(result.threads).toHaveLength(3);
+ expect(result.total).toBe(5);
+ });
+
+ it("should respect offset parameter for pagination", async () => {
+ const events: BaseEvent[] = [
+ { type: EventType.TEXT_MESSAGE_START, messageId: "msg1", role: "user" } as TextMessageStartEvent,
+ { type: EventType.TEXT_MESSAGE_CONTENT, messageId: "msg1", delta: "Hello" } as TextMessageContentEvent,
+ { type: EventType.TEXT_MESSAGE_END, messageId: "msg1" } as TextMessageEndEvent,
+ ];
+
+ const agent = new MockAgent(events);
+
+ // Create 5 threads
+ for (let i = 0; i < 5; i++) {
+ const observable = runner.run({
+ threadId: `thread-${i}`,
+ agent,
+ input: { threadId: `thread-${i}`, runId: `run-${i}`, messages: [], state: {} },
+ });
+ await firstValueFrom(observable.pipe(toArray()));
+ }
+
+ const page1 = await runner.listThreads({ limit: 2, offset: 0 });
+ const page2 = await runner.listThreads({ limit: 2, offset: 2 });
+
+ expect(page1.threads).toHaveLength(2);
+ expect(page2.threads).toHaveLength(2);
+
+ // Ensure different threads
+ const page1Ids = page1.threads.map((t) => t.threadId);
+ const page2Ids = page2.threads.map((t) => t.threadId);
+ const overlap = page1Ids.filter((id) => page2Ids.includes(id));
+ expect(overlap).toHaveLength(0);
+ });
+
+ it("should get metadata for a specific thread", async () => {
+ const events: BaseEvent[] = [
+ { type: EventType.TEXT_MESSAGE_START, messageId: "msg1", role: "user" } as TextMessageStartEvent,
+ { type: EventType.TEXT_MESSAGE_CONTENT, messageId: "msg1", delta: "Specific thread" } as TextMessageContentEvent,
+ { type: EventType.TEXT_MESSAGE_END, messageId: "msg1" } as TextMessageEndEvent,
+ ];
+
+ const agent = new MockAgent(events);
+ const observable = runner.run({
+ threadId: "thread-specific",
+ agent,
+ input: { threadId: "thread-specific", runId: "run-1", messages: [], state: {} },
+ });
+ await firstValueFrom(observable.pipe(toArray()));
+
+ const metadata = await runner.getThreadMetadata("thread-specific");
+
+ expect(metadata).toBeDefined();
+ expect(metadata!.threadId).toBe("thread-specific");
+ expect(metadata!.firstMessage).toBe("Specific thread");
+ });
+
+ it("should return null for non-existent thread", async () => {
+ const metadata = await runner.getThreadMetadata("non-existent");
+ expect(metadata).toBeNull();
+ });
+
+ it("should sort threads by last activity (most recent first)", async () => {
+ const events: BaseEvent[] = [
+ { type: EventType.TEXT_MESSAGE_START, messageId: "msg1", role: "user" } as TextMessageStartEvent,
+ { type: EventType.TEXT_MESSAGE_CONTENT, messageId: "msg1", delta: "Hello" } as TextMessageContentEvent,
+ { type: EventType.TEXT_MESSAGE_END, messageId: "msg1" } as TextMessageEndEvent,
+ ];
+
+ const agent = new MockAgent(events);
+
+ // Create threads with delays to ensure different timestamps
+ for (let i = 0; i < 3; i++) {
+ const observable = runner.run({
+ threadId: `thread-${i}`,
+ agent,
+ input: { threadId: `thread-${i}`, runId: `run-${i}`, messages: [], state: {} },
+ });
+ await firstValueFrom(observable.pipe(toArray()));
+ await new Promise((resolve) => setTimeout(resolve, 10)); // Small delay
+ }
+
+ const result = await runner.listThreads({ limit: 10 });
+
+ // Verify descending order (most recent first)
+ for (let i = 0; i < result.threads.length - 1; i++) {
+ expect(result.threads[i].lastActivityAt).toBeGreaterThanOrEqual(result.threads[i + 1].lastActivityAt);
+ }
+ });
+});
diff --git a/packages/sqlite-runner/src/__tests__/threading-edge-cases.test.ts b/packages/sqlite-runner/src/__tests__/threading-edge-cases.test.ts
new file mode 100644
index 00000000..1dd408e5
--- /dev/null
+++ b/packages/sqlite-runner/src/__tests__/threading-edge-cases.test.ts
@@ -0,0 +1,783 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { SqliteAgentRunner } from "../sqlite-runner";
+import {
+ AbstractAgent,
+ BaseEvent,
+ RunAgentInput,
+ EventType,
+ TextMessageStartEvent,
+ TextMessageContentEvent,
+ TextMessageEndEvent,
+ Message,
+} from "@ag-ui/client";
+import { EMPTY, firstValueFrom } from "rxjs";
+import { toArray } from "rxjs/operators";
+
+type RunCallbacks = {
+ onEvent: (event: { event: BaseEvent }) => void;
+ onNewMessage?: (args: { message: Message }) => void;
+ onRunStartedEvent?: () => void;
+};
+
+class MockAgent extends AbstractAgent {
+ private events: BaseEvent[];
+
+ constructor(events: BaseEvent[] = []) {
+ super();
+ this.events = events;
+ }
+
+ async runAgent(input: RunAgentInput, callbacks: RunCallbacks): Promise {
+ if (callbacks.onRunStartedEvent) {
+ callbacks.onRunStartedEvent();
+ }
+
+ for (const event of this.events) {
+ callbacks.onEvent({ event });
+ }
+ }
+
+ clone(): AbstractAgent {
+ return new MockAgent(this.events);
+ }
+
+ protected run(): ReturnType {
+ return EMPTY;
+ }
+
+ protected connect(): ReturnType {
+ return EMPTY;
+ }
+}
+
+describe("Threading Edge Cases - SqliteAgentRunner", () => {
+ let runner: SqliteAgentRunner;
+
+ beforeEach(() => {
+ runner = new SqliteAgentRunner({ dbPath: ":memory:" });
+ });
+
+ afterEach(() => {
+ runner.close();
+ });
+
+ const createTestEvents = (text: string, id: string): BaseEvent[] => [
+ { type: EventType.TEXT_MESSAGE_START, messageId: id, role: "user" } as TextMessageStartEvent,
+ { type: EventType.TEXT_MESSAGE_CONTENT, messageId: id, delta: text } as TextMessageContentEvent,
+ { type: EventType.TEXT_MESSAGE_END, messageId: id } as TextMessageEndEvent,
+ ];
+
+ describe("Thread Creation Race Conditions", () => {
+ it("should prevent cross-user access when trying same threadId", async () => {
+ const agent1 = new MockAgent(createTestEvents("Message 1", "msg1"));
+ const agent2 = new MockAgent(createTestEvents("Message 2", "msg2"));
+
+ // Alice creates the thread first
+ await firstValueFrom(
+ runner.run({
+ threadId: "concurrent-thread",
+ agent: agent1,
+ input: { threadId: "concurrent-thread", runId: "concurrent-thread-run-1", messages: [], state: {} },
+ scope: { resourceId: "user-alice" },
+ }).pipe(toArray())
+ );
+
+ // Bob tries to run on Alice's thread - should be rejected
+ let errorThrown = false;
+ try {
+ await firstValueFrom(
+ runner.run({
+ threadId: "concurrent-thread",
+ agent: agent2,
+ input: { threadId: "concurrent-thread", runId: "concurrent-thread-run-2", messages: [], state: {} },
+ scope: { resourceId: "user-bob" },
+ }).pipe(toArray())
+ );
+ } catch (error: any) {
+ errorThrown = true;
+ expect(error.message).toBe("Unauthorized: Cannot run on thread owned by different resource");
+ }
+ expect(errorThrown).toBe(true);
+
+ // Verify Alice still owns the thread
+ const metadata = await runner.getThreadMetadata("concurrent-thread", { resourceId: "user-alice" });
+ expect(metadata).not.toBeNull();
+ expect(metadata!.resourceId).toBe("user-alice");
+
+ // Verify Bob can't access it
+ const bobMetadata = await runner.getThreadMetadata("concurrent-thread", { resourceId: "user-bob" });
+ expect(bobMetadata).toBeNull();
+ });
+
+ it("should persist state correctly after concurrent attempts", async () => {
+ const agent1 = new MockAgent(createTestEvents("Alice", "msg1"));
+ const agent2 = new MockAgent(createTestEvents("Bob", "msg2"));
+
+ // Try concurrent creation - wrap in async functions to catch synchronous throws
+ await Promise.allSettled([
+ (async () => {
+ return await firstValueFrom(
+ runner.run({
+ threadId: "race-persist",
+ agent: agent1,
+ input: { threadId: "race-persist", runId: "race-persist-run-1", messages: [], state: {} },
+ scope: { resourceId: "user-alice" },
+ }).pipe(toArray())
+ );
+ })(),
+ (async () => {
+ return await firstValueFrom(
+ runner.run({
+ threadId: "race-persist",
+ agent: agent2,
+ input: { threadId: "race-persist", runId: "race-persist-run-2", messages: [], state: {} },
+ scope: { resourceId: "user-bob" },
+ }).pipe(toArray())
+ );
+ })(),
+ ]);
+
+ // Verify database integrity - should only have one owner
+ const aliceMetadata = await runner.getThreadMetadata("race-persist", { resourceId: "user-alice" });
+ const bobMetadata = await runner.getThreadMetadata("race-persist", { resourceId: "user-bob" });
+
+ // Exactly one should have access
+ const hasAccess = [aliceMetadata, bobMetadata].filter(m => m !== null).length;
+ expect(hasAccess).toBe(1);
+ });
+ });
+
+ describe("Special Characters in ResourceIds - SQL Injection Protection", () => {
+ it("should safely handle SQL injection attempts in resourceId", async () => {
+ const agent = new MockAgent(createTestEvents("Test", "msg1"));
+
+ const injectionAttempts = [
+ "user' OR '1'='1",
+ "user'; DROP TABLE agent_runs; --",
+ "user' UNION SELECT * FROM agent_runs--",
+ "user' AND 1=1--",
+ "user\\'; DROP TABLE agent_runs; --",
+ ];
+
+ for (const resourceId of injectionAttempts) {
+ const obs = runner.run({
+ threadId: `injection-${injectionAttempts.indexOf(resourceId)}`,
+ agent,
+ input: { threadId: `injection-${injectionAttempts.indexOf(resourceId)}`, runId: `injection-${injectionAttempts.indexOf(resourceId)}-run-1`, messages: [], state: {} },
+ scope: { resourceId },
+ });
+
+ const events = await firstValueFrom(obs.pipe(toArray()));
+ expect(events.length).toBeGreaterThan(0);
+
+ // Verify the thread is only accessible by exact resourceId match
+ const metadata = await runner.getThreadMetadata(
+ `injection-${injectionAttempts.indexOf(resourceId)}`,
+ { resourceId }
+ );
+ expect(metadata).not.toBeNull();
+ expect(metadata!.resourceId).toBe(resourceId);
+
+ // Verify isolation - "legitimate" users can't access
+ const otherMetadata = await runner.getThreadMetadata(
+ `injection-${injectionAttempts.indexOf(resourceId)}`,
+ { resourceId: "user" }
+ );
+ expect(otherMetadata).toBeNull();
+ }
+
+ // Verify database structure is intact (table still exists)
+ const allThreads = await runner.listThreads({ scope: null, limit: 100 });
+ expect(allThreads.total).toBeGreaterThan(0);
+ });
+
+ it("should handle unicode and special characters in resourceId", async () => {
+ const agent = new MockAgent(createTestEvents("Test", "msg1"));
+
+ const specialIds = [
+ "user-日本語-émoji-🎉",
+ "user\nwith\nnewlines",
+ "user\twith\ttabs",
+ "user'with\"quotes'",
+ "user%wildcard%",
+ "user_underscore_",
+ ];
+
+ for (const resourceId of specialIds) {
+ const threadId = `special-${specialIds.indexOf(resourceId)}`;
+ const obs = runner.run({
+ threadId,
+ agent,
+ input: { threadId, runId: `${threadId}-run-1`, messages: [], state: {} },
+ scope: { resourceId },
+ });
+
+ const events = await firstValueFrom(obs.pipe(toArray()));
+ expect(events.length).toBeGreaterThan(0);
+
+ // Verify exact match retrieval
+ const metadata = await runner.getThreadMetadata(threadId, { resourceId });
+ expect(metadata).not.toBeNull();
+ expect(metadata!.resourceId).toBe(resourceId);
+ }
+ });
+
+ it("should handle very long resourceIds without truncation", async () => {
+ const agent = new MockAgent(createTestEvents("Test", "msg1"));
+ const longResourceId = "user-" + "a".repeat(10000); // 10KB resourceId
+
+ const obs = runner.run({
+ threadId: "long-id-thread",
+ agent,
+ input: { threadId: "long-id-thread", runId: "long-id-thread-run-1", messages: [], state: {} },
+ scope: { resourceId: longResourceId },
+ });
+
+ const events = await firstValueFrom(obs.pipe(toArray()));
+ expect(events.length).toBeGreaterThan(0);
+
+ // Verify full resourceId is stored (no truncation)
+ const metadata = await runner.getThreadMetadata("long-id-thread", { resourceId: longResourceId });
+ expect(metadata).not.toBeNull();
+ expect(metadata!.resourceId).toBe(longResourceId);
+ expect(metadata!.resourceId.length).toBe(longResourceId.length);
+ });
+ });
+
+ describe("ListThreads Edge Cases with Database Queries", () => {
+ it("should handle offset greater than total threads efficiently", async () => {
+ const agent = new MockAgent(createTestEvents("Test", "msg1"));
+
+ // Create 5 threads
+ for (let i = 0; i < 5; i++) {
+ await firstValueFrom(
+ runner.run({
+ threadId: `thread-${i}`,
+ agent,
+ input: { threadId: `thread-${i}`, runId: `thread-${i}-run-1`, messages: [], state: {} },
+ scope: { resourceId: "user-alice" },
+ }).pipe(toArray())
+ );
+ }
+
+ // Query with huge offset
+ const result = await runner.listThreads({
+ scope: { resourceId: "user-alice" },
+ limit: 10,
+ offset: 10000,
+ });
+
+ expect(result.total).toBe(5);
+ expect(result.threads).toHaveLength(0);
+ });
+
+ it("should maintain sort order across pagination", async () => {
+ const agent = new MockAgent(createTestEvents("Test", "msg1"));
+
+ // Create threads with delays to ensure different timestamps
+ for (let i = 0; i < 10; i++) {
+ await firstValueFrom(
+ runner.run({
+ threadId: `ordered-thread-${i}`,
+ agent,
+ input: { threadId: `ordered-thread-${i}`, runId: `ordered-thread-${i}-run-1`, messages: [], state: {} },
+ scope: { resourceId: "user-alice" },
+ }).pipe(toArray())
+ );
+ // Small delay to ensure different timestamps
+ await new Promise(resolve => setTimeout(resolve, 5));
+ }
+
+ // Get all threads in pages
+ const page1 = await runner.listThreads({
+ scope: { resourceId: "user-alice" },
+ limit: 4,
+ offset: 0,
+ });
+
+ const page2 = await runner.listThreads({
+ scope: { resourceId: "user-alice" },
+ limit: 4,
+ offset: 4,
+ });
+
+ // Verify descending order by lastActivityAt (most recent first)
+ const allThreads = [...page1.threads, ...page2.threads];
+ for (let i = 0; i < allThreads.length - 1; i++) {
+ expect(allThreads[i].lastActivityAt).toBeGreaterThanOrEqual(allThreads[i + 1].lastActivityAt);
+ }
+ });
+
+ it("should handle empty result set efficiently", async () => {
+ const startTime = Date.now();
+
+ const result = await runner.listThreads({
+ scope: { resourceId: "user-with-no-threads" },
+ limit: 100,
+ });
+
+ const duration = Date.now() - startTime;
+
+ expect(result.total).toBe(0);
+ expect(result.threads).toHaveLength(0);
+ expect(duration).toBeLessThan(100); // Should be fast even with high limit
+ });
+ });
+
+ describe("Thread Lifecycle with Database Persistence", () => {
+ it("should completely remove thread data after deletion", async () => {
+ const agent = new MockAgent(createTestEvents("Test", "msg1"));
+
+ // Create thread
+ await firstValueFrom(
+ runner.run({
+ threadId: "delete-complete",
+ agent,
+ input: { threadId: "delete-complete", runId: "delete-complete-run-1", messages: [], state: {} },
+ scope: { resourceId: "user-alice" },
+ }).pipe(toArray())
+ );
+
+ // Verify it exists
+ let metadata = await runner.getThreadMetadata("delete-complete", { resourceId: "user-alice" });
+ expect(metadata).not.toBeNull();
+
+ // Delete it
+ await runner.deleteThread("delete-complete", { resourceId: "user-alice" });
+
+ // Verify complete removal
+ metadata = await runner.getThreadMetadata("delete-complete", { resourceId: "user-alice" });
+ expect(metadata).toBeNull();
+
+ // Verify not in list
+ const threads = await runner.listThreads({
+ scope: { resourceId: "user-alice" },
+ limit: 100,
+ });
+ expect(threads.threads.find(t => t.threadId === "delete-complete")).toBeUndefined();
+
+ // Verify connect returns empty
+ const events = await firstValueFrom(
+ runner.connect({ threadId: "delete-complete", scope: { resourceId: "user-alice" } }).pipe(toArray())
+ );
+ expect(events).toHaveLength(0);
+ });
+
+ it("should allow thread reuse after deletion with clean state", async () => {
+ const agent1 = new MockAgent(createTestEvents("First", "msg1"));
+ const agent2 = new MockAgent(createTestEvents("Second", "msg2"));
+
+ // Create thread
+ await firstValueFrom(
+ runner.run({
+ threadId: "reuse-thread",
+ agent: agent1,
+ input: { threadId: "reuse-thread", runId: "reuse-thread-run-1", messages: [], state: {} },
+ scope: { resourceId: "user-alice", properties: { version: 1 } },
+ }).pipe(toArray())
+ );
+
+ // Delete it
+ await runner.deleteThread("reuse-thread", { resourceId: "user-alice" });
+
+ // Create new thread with same ID but different user
+ await firstValueFrom(
+ runner.run({
+ threadId: "reuse-thread",
+ agent: agent2,
+ input: { threadId: "reuse-thread", runId: "reuse-thread-run-2", messages: [], state: {} },
+ scope: { resourceId: "user-bob", properties: { version: 2 } },
+ }).pipe(toArray())
+ );
+
+ // Verify it's Bob's thread now
+ const metadata = await runner.getThreadMetadata("reuse-thread", { resourceId: "user-bob" });
+ expect(metadata).not.toBeNull();
+ expect(metadata!.resourceId).toBe("user-bob");
+ expect(metadata!.properties).toEqual({ version: 2 });
+
+ // Verify no old data
+ const events = await firstValueFrom(
+ runner.connect({ threadId: "reuse-thread", scope: { resourceId: "user-bob" } }).pipe(toArray())
+ );
+ const textEvents = events.filter(e => e.type === EventType.TEXT_MESSAGE_CONTENT) as TextMessageContentEvent[];
+ expect(textEvents.some(e => e.delta === "First")).toBe(false);
+ expect(textEvents.some(e => e.delta === "Second")).toBe(true);
+
+ // Verify Alice can't access it
+ const aliceMetadata = await runner.getThreadMetadata("reuse-thread", { resourceId: "user-alice" });
+ expect(aliceMetadata).toBeNull();
+ });
+ });
+
+ describe("Properties with JSON Serialization", () => {
+ it("should handle malformed JSON-like strings in properties", async () => {
+ const agent = new MockAgent(createTestEvents("Test", "msg1"));
+
+ const weirdProps = {
+ jsonString: '{"not":"parsed"}',
+ sqlInjection: "'; DROP TABLE agent_runs; --",
+ htmlTags: "",
+ backslashes: "\\\\\\",
+ quotes: '"""""',
+ };
+
+ const obs = runner.run({
+ threadId: "weird-props-thread",
+ agent,
+ input: { threadId: "weird-props-thread", runId: "weird-props-thread-run-1", messages: [], state: {} },
+ scope: { resourceId: "user-alice", properties: weirdProps },
+ });
+
+ const events = await firstValueFrom(obs.pipe(toArray()));
+ expect(events.length).toBeGreaterThan(0);
+
+ // Verify properties are stored and retrieved exactly as provided
+ const metadata = await runner.getThreadMetadata("weird-props-thread", { resourceId: "user-alice" });
+ expect(metadata!.properties).toEqual(weirdProps);
+ });
+
+ it("should handle very large properties (MB of data)", async () => {
+ const agent = new MockAgent(createTestEvents("Test", "msg1"));
+
+ // Create 1MB of properties data
+ const largeProps: Record = {};
+ for (let i = 0; i < 10000; i++) {
+ largeProps[`key${i}`] = "x".repeat(100);
+ }
+
+ const obs = runner.run({
+ threadId: "large-props-thread",
+ agent,
+ input: { threadId: "large-props-thread", runId: "large-props-thread-run-1", messages: [], state: {} },
+ scope: { resourceId: "user-alice", properties: largeProps },
+ });
+
+ const events = await firstValueFrom(obs.pipe(toArray()));
+ expect(events.length).toBeGreaterThan(0);
+
+ // Verify all data is preserved
+ const metadata = await runner.getThreadMetadata("large-props-thread", { resourceId: "user-alice" });
+ expect(metadata!.properties).toEqual(largeProps);
+ expect(Object.keys(metadata!.properties!).length).toBe(10000);
+ });
+
+ it("should handle nested objects and arrays in properties", async () => {
+ const agent = new MockAgent(createTestEvents("Test", "msg1"));
+
+ const nestedProps = {
+ simple: "value",
+ nested: {
+ level1: {
+ level2: {
+ level3: "deep",
+ },
+ },
+ },
+ array: [1, 2, 3, { nested: "in array" }],
+ nullValue: null,
+ booleans: [true, false],
+ numbers: [0, -1, 3.14159, Number.MAX_SAFE_INTEGER],
+ };
+
+ const obs = runner.run({
+ threadId: "nested-props-thread",
+ agent,
+ input: { threadId: "nested-props-thread", runId: "nested-props-thread-run-1", messages: [], state: {} },
+ scope: { resourceId: "user-alice", properties: nestedProps },
+ });
+
+ const events = await firstValueFrom(obs.pipe(toArray()));
+ expect(events.length).toBeGreaterThan(0);
+
+ const metadata = await runner.getThreadMetadata("nested-props-thread", { resourceId: "user-alice" });
+ expect(metadata!.properties).toEqual(nestedProps);
+ });
+ });
+
+ describe("Connect/Disconnect with Database State", () => {
+ it("should handle connection to non-existent thread", async () => {
+ const events = await firstValueFrom(
+ runner.connect({ threadId: "does-not-exist", scope: { resourceId: "user-alice" } }).pipe(toArray())
+ );
+
+ expect(events).toHaveLength(0);
+ });
+
+ it("should handle admin connection to any thread", async () => {
+ const agent = new MockAgent(createTestEvents("User message", "msg1"));
+
+ // Create as user
+ await firstValueFrom(
+ runner.run({
+ threadId: "user-thread",
+ agent,
+ input: { threadId: "user-thread", runId: "user-thread-run-1", messages: [], state: {} },
+ scope: { resourceId: "user-alice" },
+ }).pipe(toArray())
+ );
+
+ // Admin connects with null scope
+ const adminEvents = await firstValueFrom(
+ runner.connect({ threadId: "user-thread", scope: null }).pipe(toArray())
+ );
+
+ expect(adminEvents.length).toBeGreaterThan(0);
+
+ // Admin with undefined scope
+ const globalEvents = await firstValueFrom(
+ runner.connect({ threadId: "user-thread" }).pipe(toArray())
+ );
+
+ expect(globalEvents.length).toBeGreaterThan(0);
+ });
+
+ it("should handle multiple sequential connections efficiently", async () => {
+ const agent = new MockAgent(createTestEvents("Test", "msg1"));
+
+ // Create thread
+ await firstValueFrom(
+ runner.run({
+ threadId: "sequential-connect",
+ agent,
+ input: { threadId: "sequential-connect", runId: "sequential-connect-run-1", messages: [], state: {} },
+ scope: { resourceId: "user-alice" },
+ }).pipe(toArray())
+ );
+
+ // Connect multiple times sequentially
+ const startTime = Date.now();
+ for (let i = 0; i < 10; i++) {
+ const events = await firstValueFrom(
+ runner.connect({ threadId: "sequential-connect", scope: { resourceId: "user-alice" } }).pipe(toArray())
+ );
+ expect(events.length).toBeGreaterThan(0);
+ }
+ const duration = Date.now() - startTime;
+
+ // Should be reasonably fast (< 100ms for 10 connections)
+ expect(duration).toBeLessThan(1000);
+ });
+ });
+
+ describe("Resource ID Array with SQL Queries", () => {
+ it("should optimize queries with single-element array", async () => {
+ const agent = new MockAgent(createTestEvents("Test", "msg1"));
+
+ // Create thread
+ await firstValueFrom(
+ runner.run({
+ threadId: "single-array-thread",
+ agent,
+ input: { threadId: "single-array-thread", runId: "single-array-thread-run-1", messages: [], state: {} },
+ scope: { resourceId: "user-alice" },
+ }).pipe(toArray())
+ );
+
+ // Query with single-element array should work efficiently
+ const threads = await runner.listThreads({
+ scope: { resourceId: ["user-alice"] },
+ limit: 10,
+ });
+
+ expect(threads.total).toBe(1);
+ expect(threads.threads[0].threadId).toBe("single-array-thread");
+ });
+
+ it("should handle large IN clause for multi-workspace queries", async () => {
+ const agent = new MockAgent(createTestEvents("Test", "msg1"));
+
+ // Create threads in different workspaces
+ for (let i = 0; i < 10; i++) {
+ await firstValueFrom(
+ runner.run({
+ threadId: `workspace-thread-${i}`,
+ agent,
+ input: { threadId: `workspace-thread-${i}`, runId: `workspace-thread-${i}-run-1`, messages: [], state: {} },
+ scope: { resourceId: `workspace-${i}` },
+ }).pipe(toArray())
+ );
+ }
+
+ // Query with array of 100 workspaces (stress test IN clause)
+ const largeArray = Array.from({ length: 100 }, (_, i) => `workspace-${i}`);
+ const threads = await runner.listThreads({
+ scope: { resourceId: largeArray },
+ limit: 100,
+ });
+
+ // Should find the 10 we created
+ expect(threads.total).toBe(10);
+ });
+
+ it("should handle duplicate resourceIds in array efficiently", async () => {
+ const agent = new MockAgent(createTestEvents("Test", "msg1"));
+
+ // Create thread
+ await firstValueFrom(
+ runner.run({
+ threadId: "dup-array-thread",
+ agent,
+ input: { threadId: "dup-array-thread", runId: "dup-array-thread-run-1", messages: [], state: {} },
+ scope: { resourceId: "workspace-a" },
+ }).pipe(toArray())
+ );
+
+ // Query with duplicates (should still return single result)
+ const threads = await runner.listThreads({
+ scope: { resourceId: ["workspace-a", "workspace-a", "workspace-a"] },
+ limit: 10,
+ });
+
+ expect(threads.total).toBe(1);
+ expect(threads.threads[0].threadId).toBe("dup-array-thread");
+ });
+ });
+
+ describe("Suggestion Threads with Database Filtering", () => {
+ it("should exclude suggestion threads from listThreads via SQL", async () => {
+ const agent = new MockAgent(createTestEvents("Test", "msg1"));
+
+ // Create regular thread
+ await firstValueFrom(
+ runner.run({
+ threadId: "regular-thread",
+ agent,
+ input: { threadId: "regular-thread", runId: "regular-thread-run-1", messages: [], state: {} },
+ scope: { resourceId: "user-alice" },
+ }).pipe(toArray())
+ );
+
+ // Create multiple suggestion threads
+ for (let i = 0; i < 5; i++) {
+ await firstValueFrom(
+ runner.run({
+ threadId: `thread-suggestions-${i}`,
+ agent,
+ input: { threadId: `thread-suggestions-${i}`, runId: `thread-suggestions-${i}-run-1`, messages: [], state: {} },
+ scope: { resourceId: "user-alice" },
+ }).pipe(toArray())
+ );
+ }
+
+ // List should only return regular thread
+ const threads = await runner.listThreads({
+ scope: { resourceId: "user-alice" },
+ limit: 100,
+ });
+
+ expect(threads.total).toBe(1);
+ expect(threads.threads[0].threadId).toBe("regular-thread");
+ });
+
+ it("should allow direct access to suggestion threads", async () => {
+ const agent = new MockAgent(createTestEvents("Test", "msg1"));
+
+ // Create suggestion thread
+ await firstValueFrom(
+ runner.run({
+ threadId: "my-suggestions-thread",
+ agent,
+ input: { threadId: "my-suggestions-thread", runId: "my-suggestions-thread-run-1", messages: [], state: {} },
+ scope: { resourceId: "user-alice" },
+ }).pipe(toArray())
+ );
+
+ // Should be accessible via getThreadMetadata
+ const metadata = await runner.getThreadMetadata("my-suggestions-thread", { resourceId: "user-alice" });
+ expect(metadata).not.toBeNull();
+ expect(metadata!.threadId).toBe("my-suggestions-thread");
+
+ // Should be accessible via connect
+ const events = await firstValueFrom(
+ runner.connect({ threadId: "my-suggestions-thread", scope: { resourceId: "user-alice" } }).pipe(toArray())
+ );
+ expect(events.length).toBeGreaterThan(0);
+ });
+
+ it("should respect scope for suggestion threads", async () => {
+ const agent = new MockAgent(createTestEvents("Test", "msg1"));
+
+ // Alice creates suggestion thread
+ await firstValueFrom(
+ runner.run({
+ threadId: "alice-suggestions-thread",
+ agent,
+ input: { threadId: "alice-suggestions-thread", runId: "alice-suggestions-thread-run-1", messages: [], state: {} },
+ scope: { resourceId: "user-alice" },
+ }).pipe(toArray())
+ );
+
+ // Bob can't access Alice's suggestions
+ const metadata = await runner.getThreadMetadata("alice-suggestions-thread", { resourceId: "user-bob" });
+ expect(metadata).toBeNull();
+
+ // Bob can't connect
+ const events = await firstValueFrom(
+ runner.connect({ threadId: "alice-suggestions-thread", scope: { resourceId: "user-bob" } }).pipe(toArray())
+ );
+ expect(events).toHaveLength(0);
+ });
+ });
+
+ describe("Database Integrity After Edge Cases", () => {
+ it("should maintain referential integrity after multiple operations", async () => {
+ const agent = new MockAgent(createTestEvents("Test", "msg1"));
+
+ // Create, delete, recreate cycle
+ for (let cycle = 0; cycle < 3; cycle++) {
+ await firstValueFrom(
+ runner.run({
+ threadId: "integrity-thread",
+ agent,
+ input: { threadId: "integrity-thread", runId: `run-${cycle}`, messages: [], state: {} },
+ scope: { resourceId: "user-alice" },
+ }).pipe(toArray())
+ );
+
+ await runner.deleteThread("integrity-thread", { resourceId: "user-alice" });
+ }
+
+ // Final verification - database should be clean
+ const threads = await runner.listThreads({
+ scope: { resourceId: "user-alice" },
+ limit: 100,
+ });
+ expect(threads.total).toBe(0);
+ });
+
+ it("should handle database after stress test", async () => {
+ const agent = new MockAgent(createTestEvents("Test", "msg1"));
+
+ // Create many threads rapidly with unique run IDs
+ const promises = [];
+ for (let i = 0; i < 50; i++) {
+ promises.push(
+ firstValueFrom(
+ runner.run({
+ threadId: `stress-thread-${i}`,
+ agent,
+ input: { threadId: `stress-thread-${i}`, runId: `stress-run-${i}`, messages: [], state: {} },
+ scope: { resourceId: "user-alice" },
+ }).pipe(toArray())
+ )
+ );
+ }
+
+ await Promise.all(promises);
+
+ // Verify all were created correctly
+ const threads = await runner.listThreads({
+ scope: { resourceId: "user-alice" },
+ limit: 100,
+ });
+ expect(threads.total).toBe(50);
+
+ // Verify each thread is accessible
+ for (let i = 0; i < 50; i++) {
+ const metadata = await runner.getThreadMetadata(`stress-thread-${i}`, { resourceId: "user-alice" });
+ expect(metadata).not.toBeNull();
+ }
+ });
+ });
+});
diff --git a/packages/sqlite-runner/src/sqlite-runner.ts b/packages/sqlite-runner/src/sqlite-runner.ts
index 90357ab6..eb4f3691 100644
--- a/packages/sqlite-runner/src/sqlite-runner.ts
+++ b/packages/sqlite-runner/src/sqlite-runner.ts
@@ -5,6 +5,9 @@ import {
type AgentRunnerIsRunningRequest,
type AgentRunnerRunRequest,
type AgentRunnerStopRequest,
+ type AgentRunnerListThreadsRequest,
+ type AgentRunnerListThreadsResponse,
+ type ThreadMetadata,
} from "@copilotkitnext/runtime";
import { Observable, ReplaySubject } from "rxjs";
import {
@@ -13,17 +16,20 @@ import {
RunAgentInput,
EventType,
RunStartedEvent,
+ TextMessageContentEvent,
compactEvents,
} from "@ag-ui/client";
import Database from "better-sqlite3";
-const SCHEMA_VERSION = 1;
+const SCHEMA_VERSION = 3;
interface AgentRunRecord {
id: number;
thread_id: string;
run_id: string;
parent_run_id: string | null;
+ resource_id: string;
+ properties: Record | null;
events: BaseEvent[];
input: RunAgentInput;
created_at: number;
@@ -51,20 +57,20 @@ export class SqliteAgentRunner extends AgentRunner {
constructor(options: SqliteAgentRunnerOptions = {}) {
super();
const dbPath = options.dbPath ?? ":memory:";
-
+
if (!Database) {
throw new Error(
- 'better-sqlite3 is required for SqliteAgentRunner but was not found.\n' +
- 'Please install it in your project:\n' +
- ' npm install better-sqlite3\n' +
- ' or\n' +
- ' pnpm add better-sqlite3\n' +
- ' or\n' +
- ' yarn add better-sqlite3\n\n' +
- 'If you don\'t need persistence, use InMemoryAgentRunner instead.'
+ "better-sqlite3 is required for SqliteAgentRunner but was not found.\n" +
+ "Please install it in your project:\n" +
+ " npm install better-sqlite3\n" +
+ " or\n" +
+ " pnpm add better-sqlite3\n" +
+ " or\n" +
+ " yarn add better-sqlite3\n\n" +
+ "If you don't need persistence, use InMemoryAgentRunner instead.",
);
}
-
+
this.db = new Database(dbPath);
this.initializeSchema();
}
@@ -77,6 +83,8 @@ export class SqliteAgentRunner extends AgentRunner {
thread_id TEXT NOT NULL,
run_id TEXT NOT NULL UNIQUE,
parent_run_id TEXT,
+ resource_id TEXT NOT NULL DEFAULT 'global',
+ properties TEXT,
events TEXT NOT NULL,
input TEXT NOT NULL,
created_at INTEGER NOT NULL,
@@ -94,10 +102,21 @@ export class SqliteAgentRunner extends AgentRunner {
)
`);
+ // Create thread_resources table for multi-resource support
+ this.db.exec(`
+ CREATE TABLE IF NOT EXISTS thread_resources (
+ thread_id TEXT NOT NULL,
+ resource_id TEXT NOT NULL,
+ PRIMARY KEY (thread_id, resource_id)
+ )
+ `);
+
// Create indexes for efficient queries
this.db.exec(`
CREATE INDEX IF NOT EXISTS idx_thread_id ON agent_runs(thread_id);
CREATE INDEX IF NOT EXISTS idx_parent_run_id ON agent_runs(parent_run_id);
+ CREATE INDEX IF NOT EXISTS idx_resource_threads ON agent_runs(resource_id, created_at DESC);
+ CREATE INDEX IF NOT EXISTS idx_thread_resources_lookup ON thread_resources(resource_id, thread_id);
`);
// Create schema version table
@@ -108,10 +127,45 @@ export class SqliteAgentRunner extends AgentRunner {
)
`);
- // Check and set schema version
- const currentVersion = this.db
- .prepare("SELECT version FROM schema_version ORDER BY version DESC LIMIT 1")
- .get() as { version: number } | undefined;
+ // Check and migrate schema if needed
+ const currentVersion = this.db.prepare("SELECT version FROM schema_version ORDER BY version DESC LIMIT 1").get() as
+ | { version: number }
+ | undefined;
+
+ if (!currentVersion || currentVersion.version < 2) {
+ // Migration from v1 to v2: Add resource_id and properties columns
+ try {
+ this.db.exec(`ALTER TABLE agent_runs ADD COLUMN resource_id TEXT NOT NULL DEFAULT 'global'`);
+ this.db.exec(`ALTER TABLE agent_runs ADD COLUMN properties TEXT`);
+ this.db.exec(`CREATE INDEX IF NOT EXISTS idx_resource_threads ON agent_runs(resource_id, created_at DESC)`);
+ } catch (e) {
+ // Columns may already exist if created with new schema
+ }
+ }
+
+ if (!currentVersion || currentVersion.version < 3) {
+ // Migration from v2 to v3: Create thread_resources table for multi-resource support
+ try {
+ this.db.exec(`
+ CREATE TABLE IF NOT EXISTS thread_resources (
+ thread_id TEXT NOT NULL,
+ resource_id TEXT NOT NULL,
+ PRIMARY KEY (thread_id, resource_id)
+ )
+ `);
+ this.db.exec(
+ `CREATE INDEX IF NOT EXISTS idx_thread_resources_lookup ON thread_resources(resource_id, thread_id)`,
+ );
+
+ // Migrate existing data: copy resource_id from agent_runs to thread_resources
+ this.db.exec(`
+ INSERT OR IGNORE INTO thread_resources (thread_id, resource_id)
+ SELECT DISTINCT thread_id, resource_id FROM agent_runs
+ `);
+ } catch (e) {
+ // Table may already exist
+ }
+ }
if (!currentVersion || currentVersion.version < SCHEMA_VERSION) {
this.db
@@ -125,36 +179,75 @@ export class SqliteAgentRunner extends AgentRunner {
runId: string,
events: BaseEvent[],
input: RunAgentInput,
- parentRunId?: string | null
+ resourceIds: string[],
+ properties: Record | undefined,
+ parentRunId?: string | null,
): void {
// Compact ONLY the events from this run
const compactedEvents = compactEvents(events);
-
+
+ // Use first resourceId for backward compatibility in agent_runs table
+ const primaryResourceId = resourceIds[0] || "unknown";
+
const stmt = this.db.prepare(`
- INSERT INTO agent_runs (thread_id, run_id, parent_run_id, events, input, created_at, version)
- VALUES (?, ?, ?, ?, ?, ?, ?)
+ INSERT INTO agent_runs (thread_id, run_id, parent_run_id, resource_id, properties, events, input, created_at, version)
+ VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
`);
stmt.run(
threadId,
runId,
parentRunId ?? null,
+ primaryResourceId,
+ properties ? JSON.stringify(properties) : null,
JSON.stringify(compactedEvents), // Store only this run's compacted events
JSON.stringify(input),
Date.now(),
- SCHEMA_VERSION
+ SCHEMA_VERSION,
);
+
+ // Insert all resource IDs into thread_resources table
+ const resourceStmt = this.db.prepare(`
+ INSERT OR IGNORE INTO thread_resources (thread_id, resource_id)
+ VALUES (?, ?)
+ `);
+
+ for (const resourceId of resourceIds) {
+ resourceStmt.run(threadId, resourceId);
+ }
+ }
+
+ /**
+ * Check if a thread's resourceIds match the given scope.
+ * Returns true if scope is null (admin bypass) or if ANY scope resourceId matches ANY thread resourceId.
+ */
+ private matchesScope(threadId: string, scope: { resourceId: string | string[] } | null | undefined): boolean {
+ if (scope === undefined || scope === null) {
+ return true; // Undefined (global) or null (admin) - see all threads
+ }
+
+ const scopeIds = Array.isArray(scope.resourceId) ? scope.resourceId : [scope.resourceId];
+
+ // Check if ANY scope ID matches ANY of the thread's resource IDs
+ const placeholders = scopeIds.map(() => "?").join(", ");
+ const stmt = this.db.prepare(`
+ SELECT COUNT(*) as count FROM thread_resources
+ WHERE thread_id = ? AND resource_id IN (${placeholders})
+ `);
+ const result = stmt.get(threadId, ...scopeIds) as { count: number } | undefined;
+
+ return (result?.count ?? 0) > 0;
}
private getHistoricRuns(threadId: string): AgentRunRecord[] {
const stmt = this.db.prepare(`
WITH RECURSIVE run_chain AS (
-- Base case: find the root runs (those without parent)
- SELECT * FROM agent_runs
+ SELECT * FROM agent_runs
WHERE thread_id = ? AND parent_run_id IS NULL
-
+
UNION ALL
-
+
-- Recursive case: find children of current level
SELECT ar.* FROM agent_runs ar
INNER JOIN run_chain rc ON ar.parent_run_id = rc.run_id
@@ -165,24 +258,26 @@ export class SqliteAgentRunner extends AgentRunner {
`);
const rows = stmt.all(threadId, threadId) as any[];
-
- return rows.map(row => ({
+
+ return rows.map((row) => ({
id: row.id,
thread_id: row.thread_id,
run_id: row.run_id,
parent_run_id: row.parent_run_id,
+ resource_id: row.resource_id,
+ properties: row.properties ? JSON.parse(row.properties) : null,
events: JSON.parse(row.events),
input: JSON.parse(row.input),
created_at: row.created_at,
- version: row.version
+ version: row.version,
}));
}
private getLatestRunId(threadId: string): string | null {
const stmt = this.db.prepare(`
- SELECT run_id FROM agent_runs
- WHERE thread_id = ?
- ORDER BY created_at DESC
+ SELECT run_id FROM agent_runs
+ WHERE thread_id = ?
+ ORDER BY created_at DESC
LIMIT 1
`);
@@ -203,14 +298,61 @@ export class SqliteAgentRunner extends AgentRunner {
SELECT is_running, current_run_id FROM run_state WHERE thread_id = ?
`);
const result = stmt.get(threadId) as { is_running: number; current_run_id: string | null } | undefined;
-
+
return {
isRunning: result?.is_running === 1,
- currentRunId: result?.current_run_id ?? null
+ currentRunId: result?.current_run_id ?? null,
};
}
run(request: AgentRunnerRunRequest): Observable {
+ // Check if thread exists first
+ const existingThreadStmt = this.db.prepare(`
+ SELECT resource_id FROM thread_resources WHERE thread_id = ? LIMIT 1
+ `);
+ const existingThread = existingThreadStmt.get(request.threadId) as { resource_id: string } | undefined;
+
+ // SECURITY: Prevent null scope on NEW thread creation (admin must specify explicit owner)
+ // BUT allow null scope for existing threads (admin bypass)
+ if (!existingThread && request.scope === null) {
+ throw new Error(
+ "Cannot create thread with null scope. Admin users must specify an explicit resourceId for the thread owner.",
+ );
+ }
+
+ // Handle scope: undefined (not provided) defaults to global, or explicit value(s)
+ let resourceIds: string[];
+ if (request.scope === undefined) {
+ // No scope provided - default to global
+ resourceIds = ["global"];
+ } else if (request.scope === null) {
+ // Null scope on existing thread (admin bypass) - use existing resource IDs
+ resourceIds = [];
+ } else if (Array.isArray(request.scope.resourceId)) {
+ // Reject empty arrays - unclear intent
+ if (request.scope.resourceId.length === 0) {
+ throw new Error("Invalid scope: resourceId array cannot be empty");
+ }
+ // Store ALL resource IDs for multi-resource threads
+ resourceIds = request.scope.resourceId;
+ } else {
+ resourceIds = [request.scope.resourceId];
+ }
+
+ // SECURITY: Validate scope before allowing operations on existing threads
+ if (existingThread) {
+ // Thread exists - validate scope matches (null scope bypasses this check)
+ if (request.scope !== null && !this.matchesScope(request.threadId, request.scope)) {
+ throw new Error("Unauthorized: Cannot run on thread owned by different resource");
+ }
+ // For existing threads, get all existing resource IDs (don't add new ones)
+ const existingResourcesStmt = this.db.prepare(`
+ SELECT resource_id FROM thread_resources WHERE thread_id = ?
+ `);
+ const existingResources = existingResourcesStmt.all(request.threadId) as Array<{ resource_id: string }>;
+ resourceIds = existingResources.map((r) => r.resource_id);
+ }
+
// Check if thread is already running in database
const runState = this.getRunState(request.threadId);
if (runState.isRunning) {
@@ -223,13 +365,13 @@ export class SqliteAgentRunner extends AgentRunner {
// Track seen message IDs and current run events in memory for this run
const seenMessageIds = new Set();
const currentRunEvents: BaseEvent[] = [];
-
+
// Get all previously seen message IDs from historic runs
const historicRuns = this.getHistoricRuns(request.threadId);
const historicMessageIds = new Set();
for (const run of historicRuns) {
for (const event of run.events) {
- if ('messageId' in event && typeof event.messageId === 'string') {
+ if ("messageId" in event && typeof event.messageId === "string") {
historicMessageIds.add(event.messageId);
}
if (event.type === EventType.RUN_STARTED) {
@@ -242,11 +384,14 @@ export class SqliteAgentRunner extends AgentRunner {
}
}
- // Get or create subject for this thread's connections
+ // Create a fresh subject for this thread's connections
+ // Note: We must create a new ReplaySubject for each run because we call .complete()
+ // at the end of the run. Reusing a completed subject would cause all subsequent
+ // events to become no-ops and any connect() subscribers would receive immediate completion.
const nextSubject = new ReplaySubject(Infinity);
const prevConnection = ACTIVE_CONNECTIONS.get(request.threadId);
const prevSubject = prevConnection?.subject;
-
+
// Create a subject for run() return value
const runSubject = new ReplaySubject(Infinity);
@@ -263,7 +408,7 @@ export class SqliteAgentRunner extends AgentRunner {
const runAgent = async () => {
// Get parent run ID for chaining
const parentRunId = this.getLatestRunId(request.threadId);
-
+
try {
await request.agent.runAgent(request.input, {
onEvent: ({ event }) => {
@@ -272,15 +417,11 @@ export class SqliteAgentRunner extends AgentRunner {
const runStartedEvent = event as RunStartedEvent;
if (!runStartedEvent.input) {
const sanitizedMessages = request.input.messages
- ? request.input.messages.filter(
- (message) => !historicMessageIds.has(message.id),
- )
+ ? request.input.messages.filter((message) => !historicMessageIds.has(message.id))
: undefined;
const updatedInput = {
...request.input,
- ...(sanitizedMessages !== undefined
- ? { messages: sanitizedMessages }
- : {}),
+ ...(sanitizedMessages !== undefined ? { messages: sanitizedMessages } : {}),
};
processedEvent = {
...runStartedEvent,
@@ -310,7 +451,7 @@ export class SqliteAgentRunner extends AgentRunner {
}
},
});
-
+
const connection = ACTIVE_CONNECTIONS.get(request.threadId);
const appendedEvents = finalizeRunEvents(currentRunEvents, {
stopRequested: connection?.stopRequested ?? false,
@@ -326,9 +467,11 @@ export class SqliteAgentRunner extends AgentRunner {
request.input.runId,
currentRunEvents,
request.input,
- parentRunId
+ resourceIds,
+ request.scope?.properties,
+ parentRunId,
);
-
+
// Mark run as complete in database
this.setRunState(request.threadId, false);
@@ -361,10 +504,12 @@ export class SqliteAgentRunner extends AgentRunner {
request.input.runId,
currentRunEvents,
request.input,
- parentRunId
+ resourceIds,
+ request.scope?.properties,
+ parentRunId,
);
}
-
+
// Mark run as complete in database
this.setRunState(request.threadId, false);
@@ -384,16 +529,7 @@ export class SqliteAgentRunner extends AgentRunner {
}
};
- // Bridge previous events if they exist
- if (prevSubject) {
- prevSubject.subscribe({
- next: (e) => nextSubject.next(e),
- error: (err) => nextSubject.error(err),
- complete: () => {
- // Don't complete nextSubject here - it needs to stay open for new events
- },
- });
- }
+ // No need to bridge - we reuse the same subject for reconnections
// Start the agent execution immediately (not lazily)
runAgent();
@@ -405,48 +541,56 @@ export class SqliteAgentRunner extends AgentRunner {
connect(request: AgentRunnerConnectRequest): Observable {
const connectionSubject = new ReplaySubject(Infinity);
+ // Check if thread exists and matches scope
+ if (!this.matchesScope(request.threadId, request.scope)) {
+ // No thread or scope mismatch - return empty (404)
+ connectionSubject.complete();
+ return connectionSubject.asObservable();
+ }
+
// Load historic runs from database
const historicRuns = this.getHistoricRuns(request.threadId);
-
+
// Collect all historic events from database
const allHistoricEvents: BaseEvent[] = [];
for (const run of historicRuns) {
allHistoricEvents.push(...run.events);
}
-
+
// Compact all events together before emitting
const compactedEvents = compactEvents(allHistoricEvents);
-
+
// Emit compacted events and track message IDs
const emittedMessageIds = new Set();
for (const event of compactedEvents) {
connectionSubject.next(event);
- if ('messageId' in event && typeof event.messageId === 'string') {
+ if ("messageId" in event && typeof event.messageId === "string") {
emittedMessageIds.add(event.messageId);
}
}
-
+
// Bridge active run to connection if exists
const activeConnection = ACTIVE_CONNECTIONS.get(request.threadId);
const runState = this.getRunState(request.threadId);
+ const activeSubject = activeConnection?.subject;
- if (activeConnection && (runState.isRunning || activeConnection.stopRequested)) {
- activeConnection.subject.subscribe({
+ if (activeConnection && activeSubject && (runState.isRunning || activeConnection.stopRequested)) {
+ activeSubject.subscribe({
next: (event) => {
// Skip message events that we've already emitted from historic
- if ('messageId' in event && typeof event.messageId === 'string' && emittedMessageIds.has(event.messageId)) {
+ if ("messageId" in event && typeof event.messageId === "string" && emittedMessageIds.has(event.messageId)) {
return;
}
connectionSubject.next(event);
},
complete: () => connectionSubject.complete(),
- error: (err) => connectionSubject.error(err)
+ error: (err) => connectionSubject.error(err),
});
} else {
// No active run, complete after historic events
connectionSubject.complete();
}
-
+
return connectionSubject.asObservable();
}
@@ -486,6 +630,264 @@ export class SqliteAgentRunner extends AgentRunner {
}
}
+ async listThreads(request: AgentRunnerListThreadsRequest): Promise {
+ const limit = request.limit ?? 50;
+ const offset = request.offset ?? 0;
+
+ // Build WHERE clause for scope filtering using thread_resources
+ let scopeJoin = "";
+ let scopeCondition = "";
+ let scopeParams: string[] = [];
+
+ if (request.scope !== undefined && request.scope !== null) {
+ const scopeIds = Array.isArray(request.scope.resourceId) ? request.scope.resourceId : [request.scope.resourceId];
+
+ // Short-circuit: empty array means no access to any threads
+ if (scopeIds.length === 0) {
+ return { threads: [], total: 0 };
+ }
+
+ scopeJoin = " INNER JOIN thread_resources tr ON ar.thread_id = tr.thread_id";
+
+ if (scopeIds.length === 1) {
+ scopeCondition = " AND tr.resource_id = ?";
+ scopeParams = [scopeIds[0] ?? ""];
+ } else {
+ // Filter out any undefined values
+ const validIds = scopeIds.filter((id): id is string => id !== undefined);
+ // If all values were undefined, return empty
+ if (validIds.length === 0) {
+ return { threads: [], total: 0 };
+ }
+ const placeholders = validIds.map(() => "?").join(", ");
+ scopeCondition = ` AND tr.resource_id IN (${placeholders})`;
+ scopeParams = validIds;
+ }
+ }
+
+ // Get total count of threads (excluding suggestion threads)
+ const countStmt = this.db.prepare(`
+ SELECT COUNT(DISTINCT ar.thread_id) as total
+ FROM agent_runs ar${scopeJoin}
+ WHERE ar.thread_id NOT LIKE '%-suggestions-%'${scopeCondition}
+ `);
+ const countResult = countStmt.get(...scopeParams) as { total: number };
+ const total = countResult.total;
+
+ // Get thread metadata with pagination
+ // Exclude suggestion threads (those with '-suggestions-' in the ID)
+ const stmt = this.db.prepare(`
+ SELECT
+ ar.thread_id,
+ ar.resource_id,
+ MIN(ar.created_at) as first_created_at,
+ MAX(ar.created_at) as last_activity_at,
+ (SELECT events FROM agent_runs WHERE thread_id = ar.thread_id ORDER BY created_at ASC LIMIT 1) as first_run_events,
+ (SELECT properties FROM agent_runs WHERE thread_id = ar.thread_id LIMIT 1) as properties
+ FROM agent_runs ar${scopeJoin}
+ WHERE ar.thread_id NOT LIKE '%-suggestions-%'${scopeCondition}
+ GROUP BY ar.thread_id
+ ORDER BY last_activity_at DESC
+ LIMIT ? OFFSET ?
+ `);
+
+ const rows = stmt.all(...scopeParams, limit, offset) as Array<{
+ thread_id: string;
+ resource_id: string;
+ first_created_at: number;
+ last_activity_at: number;
+ first_run_events: string;
+ properties: string | null;
+ }>;
+
+ const threads: ThreadMetadata[] = [];
+
+ for (const row of rows) {
+ const runState = this.getRunState(row.thread_id);
+
+ // Parse first run events to extract first message
+ let firstMessage: string | undefined;
+ try {
+ const events = JSON.parse(row.first_run_events) as BaseEvent[];
+ const textContent = events.find((e) => e.type === EventType.TEXT_MESSAGE_CONTENT) as
+ | TextMessageContentEvent
+ | undefined;
+ if (textContent?.delta) {
+ firstMessage = textContent.delta.substring(0, 100); // Truncate to 100 chars
+ }
+ } catch {
+ // Ignore parse errors
+ }
+
+ // Count messages in this thread
+ const messageCountStmt = this.db.prepare(`
+ SELECT events FROM agent_runs WHERE thread_id = ?
+ `);
+ const allRuns = messageCountStmt.all(row.thread_id) as Array<{ events: string }>;
+
+ const messageIds = new Set();
+ for (const run of allRuns) {
+ try {
+ const events = JSON.parse(run.events) as BaseEvent[];
+ for (const event of events) {
+ if ("messageId" in event && typeof event.messageId === "string") {
+ messageIds.add(event.messageId);
+ }
+ }
+ } catch {
+ // Ignore parse errors
+ }
+ }
+
+ // Parse properties from JSON
+ let properties: Record | undefined;
+ if (row.properties) {
+ try {
+ properties = JSON.parse(row.properties);
+ } catch {
+ // Ignore parse errors
+ }
+ }
+
+ threads.push({
+ threadId: row.thread_id,
+ createdAt: row.first_created_at,
+ lastActivityAt: row.last_activity_at,
+ isRunning: runState.isRunning,
+ messageCount: messageIds.size,
+ firstMessage,
+ resourceId: row.resource_id,
+ properties,
+ });
+ }
+
+ return { threads, total };
+ }
+
+ async getThreadMetadata(
+ threadId: string,
+ scope?: { resourceId: string | string[] } | null,
+ ): Promise {
+ // Check if thread exists and matches scope
+ if (!this.matchesScope(threadId, scope)) {
+ return null; // Thread doesn't exist or scope mismatch (404)
+ }
+
+ const stmt = this.db.prepare(`
+ SELECT
+ thread_id,
+ resource_id,
+ MIN(created_at) as first_created_at,
+ MAX(created_at) as last_activity_at,
+ (SELECT events FROM agent_runs WHERE thread_id = ? ORDER BY created_at ASC LIMIT 1) as first_run_events,
+ (SELECT properties FROM agent_runs WHERE thread_id = ? LIMIT 1) as properties
+ FROM agent_runs
+ WHERE thread_id = ?
+ GROUP BY thread_id
+ `);
+
+ const row = stmt.get(threadId, threadId, threadId) as
+ | {
+ thread_id: string;
+ resource_id: string;
+ first_created_at: number;
+ last_activity_at: number;
+ first_run_events: string;
+ properties: string | null;
+ }
+ | undefined;
+
+ if (!row) {
+ return null;
+ }
+
+ const runState = this.getRunState(row.thread_id);
+
+ // Parse first run events to extract first message
+ let firstMessage: string | undefined;
+ try {
+ const events = JSON.parse(row.first_run_events) as BaseEvent[];
+ const textContent = events.find((e) => e.type === EventType.TEXT_MESSAGE_CONTENT) as
+ | TextMessageContentEvent
+ | undefined;
+ if (textContent?.delta) {
+ firstMessage = textContent.delta.substring(0, 100);
+ }
+ } catch {
+ // Ignore parse errors
+ }
+
+ // Count messages in this thread
+ const messageCountStmt = this.db.prepare(`
+ SELECT events FROM agent_runs WHERE thread_id = ?
+ `);
+ const allRuns = messageCountStmt.all(threadId) as Array<{ events: string }>;
+
+ const messageIds = new Set();
+ for (const run of allRuns) {
+ try {
+ const events = JSON.parse(run.events) as BaseEvent[];
+ for (const event of events) {
+ if ("messageId" in event && typeof event.messageId === "string") {
+ messageIds.add(event.messageId);
+ }
+ }
+ } catch {
+ // Ignore parse errors
+ }
+ }
+
+ // Parse properties from JSON
+ let properties: Record | undefined;
+ if (row.properties) {
+ try {
+ properties = JSON.parse(row.properties);
+ } catch {
+ // Ignore parse errors
+ }
+ }
+
+ return {
+ threadId: row.thread_id,
+ createdAt: row.first_created_at,
+ lastActivityAt: row.last_activity_at,
+ isRunning: runState.isRunning,
+ messageCount: messageIds.size,
+ firstMessage,
+ resourceId: row.resource_id,
+ properties,
+ };
+ }
+
+ async deleteThread(threadId: string, scope?: { resourceId: string | string[] } | null): Promise {
+ // Check if thread exists and matches scope
+ if (!this.matchesScope(threadId, scope)) {
+ return; // Silently succeed (idempotent)
+ }
+
+ const deleteRunsStmt = this.db.prepare(`
+ DELETE FROM agent_runs WHERE thread_id = ?
+ `);
+ deleteRunsStmt.run(threadId);
+
+ const deleteResourcesStmt = this.db.prepare(`
+ DELETE FROM thread_resources WHERE thread_id = ?
+ `);
+ deleteResourcesStmt.run(threadId);
+
+ const deleteRunStateStmt = this.db.prepare(`
+ DELETE FROM run_state WHERE thread_id = ?
+ `);
+ deleteRunStateStmt.run(threadId);
+
+ // Complete and remove the active connection for this thread
+ const activeConnection = ACTIVE_CONNECTIONS.get(threadId);
+ if (activeConnection) {
+ activeConnection.subject.complete();
+ ACTIVE_CONNECTIONS.delete(threadId);
+ }
+ }
+
/**
* Close the database connection (for cleanup)
*/
diff --git a/turbo.json b/turbo.json
index 297f5b88..288c1491 100644
--- a/turbo.json
+++ b/turbo.json
@@ -16,14 +16,7 @@
},
"test": {
"dependsOn": ["^build"],
- "inputs": [
- "src/**/*.ts",
- "src/**/*.tsx",
- "**/__tests__/**",
- "**/*.test.*",
- "**/*.spec.*"
- ],
- "outputs": ["coverage/**"],
+ "inputs": ["src/**/*.ts", "src/**/*.tsx", "**/__tests__/**", "**/*.test.*", "**/*.spec.*"],
"env": ["LOG_LEVEL", "NODE_ENV"]
},
"test:watch": {
@@ -33,13 +26,7 @@
},
"test:coverage": {
"dependsOn": ["^build"],
- "inputs": [
- "src/**/*.ts",
- "src/**/*.tsx",
- "**/__tests__/**",
- "**/*.test.*",
- "**/*.spec.*"
- ],
+ "inputs": ["src/**/*.ts", "src/**/*.tsx", "**/__tests__/**", "**/*.test.*", "**/*.spec.*"],
"outputs": ["coverage/**"],
"env": ["LOG_LEVEL", "NODE_ENV"]
},
@@ -88,10 +75,7 @@
"persistent": true
},
"storybook:build": {
- "outputs": [
- "apps/react/storybook/storybook-static/**",
- "apps/angular/storybook/storybook-static/**"
- ]
+ "outputs": ["apps/react/storybook/storybook-static/**", "apps/angular/storybook/storybook-static/**"]
},
"clean": {
"cache": false,
- Tool: {name} | Status: {status} | Location: {args.location} |
+ Tool: {name} | Status: {status} | Location: {args.location} |
{result && ` Result: ${JSON.stringify(result)}`}
),
@@ -127,21 +128,25 @@ describe("CopilotChat E2E - Chat Basics and Streaming Patterns", () => {
// Stream: RUN_STARTED → TEXT_MESSAGE_CHUNK → TOOL_CALL_CHUNK → TOOL_CALL_RESULT → RUN_FINISHED
agent.emit(runStartedEvent());
agent.emit(textChunkEvent(messageId, "Let me check the weather for you."));
-
+
// Start tool call with partial args
- agent.emit(toolCallChunkEvent({
- toolCallId,
- toolCallName: "getWeather",
- parentMessageId: messageId,
- delta: '{"location":"Paris"',
- }));
+ agent.emit(
+ toolCallChunkEvent({
+ toolCallId,
+ toolCallName: "getWeather",
+ parentMessageId: messageId,
+ delta: '{"location":"Paris"',
+ }),
+ );
// Continue streaming args
- agent.emit(toolCallChunkEvent({
- toolCallId,
- parentMessageId: messageId,
- delta: ',"unit":"celsius"}',
- }));
+ agent.emit(
+ toolCallChunkEvent({
+ toolCallId,
+ parentMessageId: messageId,
+ delta: ',"unit":"celsius"}',
+ }),
+ );
// Wait for tool to render with complete args and verify name is provided
await waitFor(() => {
@@ -151,11 +156,13 @@ describe("CopilotChat E2E - Chat Basics and Streaming Patterns", () => {
});
// Send tool result
- agent.emit(toolCallResultEvent({
- toolCallId,
- messageId: `${messageId}_result`,
- content: JSON.stringify({ temperature: 22, condition: "Sunny" }),
- }));
+ agent.emit(
+ toolCallResultEvent({
+ toolCallId,
+ messageId: `${messageId}_result`,
+ content: JSON.stringify({ temperature: 22, condition: "Sunny" }),
+ }),
+ );
// Check result appears
await waitFor(() => {
@@ -214,20 +221,24 @@ describe("CopilotChat E2E - Chat Basics and Streaming Patterns", () => {
agent.emit(textChunkEvent(messageId, "I'll check both for you."));
// Start first tool call (weather) with complete JSON in one chunk
- agent.emit(toolCallChunkEvent({
- toolCallId: toolCallId1,
- toolCallName: "getWeather",
- parentMessageId: messageId,
- delta: '{"location":"London"}',
- }));
-
- // Start second tool call (time) with complete JSON in one chunk
- agent.emit(toolCallChunkEvent({
- toolCallId: toolCallId2,
- toolCallName: "getTime",
- parentMessageId: messageId,
- delta: '{"timezone":"UTC"}',
- }));
+ agent.emit(
+ toolCallChunkEvent({
+ toolCallId: toolCallId1,
+ toolCallName: "getWeather",
+ parentMessageId: messageId,
+ delta: '{"location":"London"}',
+ }),
+ );
+
+ // Start second tool call (time) with complete JSON in one chunk
+ agent.emit(
+ toolCallChunkEvent({
+ toolCallId: toolCallId2,
+ toolCallName: "getTime",
+ parentMessageId: messageId,
+ delta: '{"timezone":"UTC"}',
+ }),
+ );
// Both tools should render with partial/complete args
await waitFor(() => {
@@ -236,23 +247,27 @@ describe("CopilotChat E2E - Chat Basics and Streaming Patterns", () => {
});
// Send results in different order
- agent.emit(toolCallResultEvent({
- toolCallId: toolCallId2,
- messageId: `${messageId}_result2`,
- content: JSON.stringify({ time: "12:00 PM" }),
- }));
-
- agent.emit(toolCallResultEvent({
- toolCallId: toolCallId1,
- messageId: `${messageId}_result1`,
- content: JSON.stringify({ temp: 18, condition: "Cloudy" }),
- }));
+ agent.emit(
+ toolCallResultEvent({
+ toolCallId: toolCallId2,
+ messageId: `${messageId}_result2`,
+ content: JSON.stringify({ time: "12:00 PM" }),
+ }),
+ );
+
+ agent.emit(
+ toolCallResultEvent({
+ toolCallId: toolCallId1,
+ messageId: `${messageId}_result1`,
+ content: JSON.stringify({ temp: 18, condition: "Cloudy" }),
+ }),
+ );
// Both results should appear with correct names
await waitFor(() => {
const weatherTool = screen.getByTestId("weather-London");
const timeTool = screen.getByTestId("time-UTC");
-
+
expect(weatherTool.textContent).toContain("[getWeather]");
expect(weatherTool.textContent).toContain("18");
expect(weatherTool.textContent).toContain("Cloudy");
@@ -296,14 +311,16 @@ describe("CopilotChat E2E - Chat Basics and Streaming Patterns", () => {
const toolCallId = testId("tc");
agent.emit(runStartedEvent());
-
+
// Call an undefined tool
- agent.emit(toolCallChunkEvent({
- toolCallId,
- toolCallName: "unknownTool",
- parentMessageId: messageId,
- delta: '{"param":"value"}',
- }));
+ agent.emit(
+ toolCallChunkEvent({
+ toolCallId,
+ toolCallName: "unknownTool",
+ parentMessageId: messageId,
+ delta: '{"param":"value"}',
+ }),
+ );
// Wildcard renderer should handle it
await waitFor(() => {
@@ -352,12 +369,14 @@ describe("CopilotChat E2E - Chat Basics and Streaming Patterns", () => {
agent.emit(runStartedEvent());
// Call an undefined tool with a specific name
- agent.emit(toolCallChunkEvent({
- toolCallId,
- toolCallName: "myCustomTool",
- parentMessageId: messageId,
- delta: '{"param":"test","value":123}',
- }));
+ agent.emit(
+ toolCallChunkEvent({
+ toolCallId,
+ toolCallName: "myCustomTool",
+ parentMessageId: messageId,
+ delta: '{"param":"test","value":123}',
+ }),
+ );
// Wildcard renderer should receive the actual tool name, not "*"
await waitFor(() => {
@@ -386,9 +405,7 @@ describe("CopilotChat E2E - Chat Basics and Streaming Patterns", () => {
defineToolCallRenderer({
name: "testTool",
args: z.object({ value: z.string() }),
- render: ({ args }) => (
- Tool: {args.value}
- ),
+ render: ({ args }) => Tool: {args.value}
,
}),
] as unknown as ReactToolCallRenderer
- Specific: {args.value}
-
- ),
+ render: ({ args }) => Specific: {args.value}
,
}),
defineToolCallRenderer({
name: "*",
args: z.any(),
- render: ({ name }) => (
-
- Wildcard: {name}
-
- ),
+ render: ({ name }) => Wildcard: {name}
,
}),
] as unknown as ReactToolCallRenderer
+ {error ? (
+
+
+ );
+
+ return renderSlot(container, Container, {
+ className,
+ children: content,
+ });
+}
+
+const Container: React.FC
+
+ ) : isLoading && threads.length === 0 ? (
+ Failed to load threads: {error.message}
+ +Loading threads...
+ ) : threads.length === 0 ? (
+ No threads yet
+ ) : (
+ threadItems
+ )}
+
+ {children}
+
+);
+
+const NewThreadButton: React.FC
+
+ {onDelete && (
+
+ )}
+
+ );
+};
+
+export function CopilotThreadList(props: CopilotThreadListProps) {
+ const existingConfig = useCopilotChatConfiguration();
+
+ // If no configuration provider exists, create one
+ if (!existingConfig) {
+ return (
+
- {stateSnapshot ? JSON.stringify(stateSnapshot) : "no-state"}
-
+ {stateSnapshot ? JSON.stringify(stateSnapshot) : "no-state"}
);
};
@@ -464,9 +459,10 @@ describe("CopilotKitProvider custom message renderers E2E", () => {
// Verify the captured props are meaningful
expect(capturedProps).toBeTruthy();
- expect(typeof capturedProps?.messageIndex).toBe("number");
- expect(typeof capturedProps?.messageIndexInRun).toBe("number");
- expect(typeof capturedProps?.numberOfMessagesInRun).toBe("number");
+ const { messageIndex, messageIndexInRun, numberOfMessagesInRun } = capturedProps!;
+ expect(typeof messageIndex).toBe("number");
+ expect(typeof messageIndexInRun).toBe("number");
+ expect(typeof numberOfMessagesInRun).toBe("number");
});
it("works across multi-turn conversations", async () => {
@@ -567,10 +563,7 @@ describe("CopilotKitProvider custom message renderers E2E", () => {
renderWithCopilotKit({
agent,
- renderCustomMessages: [
- { render: NullRenderer },
- { render: FallbackRenderer },
- ],
+ renderCustomMessages: [{ render: NullRenderer }, { render: FallbackRenderer }],
});
const input = await screen.findByRole("textbox");
@@ -665,4 +658,150 @@ describe("CopilotKitProvider custom message renderers E2E", () => {
expect(receivedSnapshots.some((s) => s.messageId === msg1)).toBe(true);
expect(receivedSnapshots.some((s) => s.messageId === msg2)).toBe(true);
});
+
+ it("should render custom messages for user messages without runId", async () => {
+ const agent = new MockStepwiseAgent();
+ let receivedRunId: string | undefined;
+
+ const Renderer: React.FC{runId || "no-run"}
;
+ };
+
+ renderWithCopilotKit({
+ agent,
+ renderCustomMessages: [{ render: Renderer }],
+ });
+
+ const input = await screen.findByRole("textbox");
+ fireEvent.change(input, { target: { value: "Test message" } });
+ fireEvent.keyDown(input, { key: "Enter", code: "Enter" });
+
+ await waitFor(() => {
+ expect(screen.getByText("Test message")).toBeDefined();
+ });
+
+ // Should handle null/empty runId gracefully
+ expect(receivedRunId).toBe("");
+ });
+
+ // Note: Skipping error handling test because React render errors need Error Boundaries
+ // Our try-catch in the hook catches errors during component creation but not during render
+ // This would require wrapping custom renderers in an Error Boundary to properly handle
+ it.skip("should continue rendering messages even when custom renderer throws error", async () => {
+ const agent = new MockStepwiseAgent();
+ let renderCount = 0;
+
+ const ErrorRenderer: React.FC
+
+ {copilotkit.resourceId}
;
+ };
+
+ const { container } = render(
+
+ {Array.isArray(resourceId) ? resourceId.join(",") : resourceId}
+
+ );
+ };
+
+ const { container } = render(
+ {copilotkit.resourceId === undefined ? "undefined" : "defined"}
;
+ };
+
+ const { container } = render(
+
+ {Array.isArray(resourceId) && resourceId.length === 0 ? "empty" : "not-empty"}
+
+ );
+ };
+
+ const { container } = render(
+ {copilotkit.resourceId}
;
+ };
+
+ const { container } = render(
+ {copilotkit.resourceId}
;
+ };
+
+ const { container, rerender } = render(
+
+ {Array.isArray(resourceId) ? resourceId.join(",") : resourceId}
+
+ );
+ };
+
+ const { container, rerender } = render(
+ {copilotkit.resourceId === undefined ? "undefined" : "defined"}
;
+ };
+
+ const { container, rerender } = render(
+ {typeof setResourceId}
;
+ };
+
+ const { container } = render(
+
+ {copilotkit.resourceId}
+
+
+ );
+ };
+
+ const { getByTestId, getByText } = render(
+
+
+ {Array.isArray(resourceId) ? resourceId.join(",") : resourceId}
+
+
+
+ );
+ };
+
+ const { getByTestId, getByText } = render(
+
+
+ {copilotkit.resourceId === undefined ? "undefined" : "defined"}
+
+
+
+ );
+ };
+
+ const { getByTestId, getByText } = render(
+
+ {copilotkit.resourceId}
+
+
+ );
+ };
+
+ const { getByTestId, getByText } = render(
+ Test
+ Test
+ Test
+ Test
+ Test
+ {(copilotkit.resourceId as string).length}
;
+ };
+
+ const { container } = render(
+ {Array.isArray(resourceId) ? resourceId.length : 0}
;
+ };
+
+ const { container } = render(
+ {copilotkit.resourceId}
;
+ };
+
+ const { container } = render(
+
+ {Array.isArray(resourceId) ? resourceId.join(",") : resourceId}
+
+ );
+ };
+
+ const { container } = render(
+ {copilotkit.resourceId}
;
+ };
+
+ const { container } = render(
+
+ {Array.isArray(resourceId) ? resourceId.join(",") : resourceId}
+
+ );
+ };
+
+ const { container } = render(
+ {copilotkit.resourceId}
;
+ };
+
+ const { getByTestId } = render(
+ <>
+