@copilotkitnext/runtime 0.0.17 → 0.0.19-threads-and-attachements.0

package/dist/index.d.mts

@@ -1,4 +1,5 @@
-import { MaybePromise, NonEmptyRecord } from '@copilotkitnext/shared';
+import { MaybePromise, ThreadMetadata, NonEmptyRecord } from '@copilotkitnext/shared';
+export { ThreadMetadata, finalizeRunEvents } from '@copilotkitnext/shared';
 import { AbstractAgent, RunAgentInput, BaseEvent } from '@ag-ui/client';
 import { Observable } from 'rxjs';
 import * as hono_hono_base from 'hono/hono-base';
@@ -47,13 +48,26 @@ declare abstract class TranscriptionService {
     abstract transcribeFile(options: TranscribeFileOptions): Promise<string>;
 }
 
+/**
+ * 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).
+ */
+interface ResourceScope {
+    resourceId: string | string[];
+    properties?: Record<string, any>;
+}
 interface AgentRunnerRunRequest {
     threadId: string;
     agent: AbstractAgent;
     input: RunAgentInput;
+    scope?: ResourceScope | null;
 }
 interface AgentRunnerConnectRequest {
     threadId: string;
+    scope?: ResourceScope | null;
 }
 interface AgentRunnerIsRunningRequest {
     threadId: string;
@@ -61,14 +75,27 @@ interface AgentRunnerIsRunningRequest {
 interface AgentRunnerStopRequest {
     threadId: string;
 }
+interface AgentRunnerListThreadsRequest {
+    scope?: ResourceScope | null;
+    limit?: number;
+    offset?: number;
+}
+interface AgentRunnerListThreadsResponse {
+    threads: ThreadMetadata[];
+    total: number;
+}
 declare abstract class AgentRunner {
     abstract run(request: AgentRunnerRunRequest): Observable<BaseEvent>;
     abstract connect(request: AgentRunnerConnectRequest): Observable<BaseEvent>;
     abstract isRunning(request: AgentRunnerIsRunningRequest): Promise<boolean>;
     abstract stop(request: AgentRunnerStopRequest): Promise<boolean | undefined>;
+    abstract listThreads(request: AgentRunnerListThreadsRequest): Promise<AgentRunnerListThreadsResponse>;
+    abstract getThreadMetadata(threadId: string, scope?: ResourceScope | null): Promise<ThreadMetadata | null>;
+    abstract deleteThread(threadId: string, scope?: ResourceScope | null): Promise<void>;
 }
 
 declare const VERSION: string;
+
 /**
  * Options used to construct a `CopilotRuntime` instance.
  */
@@ -83,17 +110,115 @@ 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<ResourceScope | null>;
+    /**
+     * 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.
  */
 declare 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: (context: {
+        request: Request;
+        clientDeclared?: string | string[];
+    }) => Promise<ResourceScope>;
+    /**
+     * 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 });
+     * ```
+     */
+    static parseClientDeclaredResourceId(request: Request): string | string[] | undefined;
     agents: CopilotRuntimeOptions["agents"];
     transcriptionService: CopilotRuntimeOptions["transcriptionService"];
     beforeRequestMiddleware: CopilotRuntimeOptions["beforeRequestMiddleware"];
     afterRequestMiddleware: CopilotRuntimeOptions["afterRequestMiddleware"];
     runner: AgentRunner;
-    constructor({ agents, transcriptionService, beforeRequestMiddleware, afterRequestMiddleware, runner, }: CopilotRuntimeOptions);
+    resolveThreadsScope: (context: {
+        request: Request;
+        clientDeclared?: string | string[];
+    }) => Promise<ResourceScope | null>;
+    private suppressResourceIdWarning;
+    constructor({ agents, transcriptionService, beforeRequestMiddleware, afterRequestMiddleware, runner, resolveThreadsScope, suppressResourceIdWarning, }: CopilotRuntimeOptions);
+    private logGlobalScopeWarning;
 }
 
 interface CopilotEndpointParams {
@@ -166,6 +291,41 @@ declare function createCopilotEndpoint({ runtime, basePath }: CopilotEndpointPar
             status: hono_utils_http_status.StatusCode;
         };
     };
+} & {
+    [x: `${string}/threads`]: {
+        $get: {
+            input: {};
+            output: {};
+            outputFormat: string;
+            status: hono_utils_http_status.StatusCode;
+        };
+    };
+} & {
+    [x: `${string}/threads/:threadId`]: {
+        $get: {
+            input: {
+                param: {
+                    threadId: string;
+                };
+            };
+            output: {};
+            outputFormat: string;
+            status: hono_utils_http_status.StatusCode;
+        };
+    };
+} & {
+    [x: `${string}/threads/:threadId`]: {
+        $delete: {
+            input: {
+                param: {
+                    threadId: string;
+                };
+            };
+            output: {};
+            outputFormat: string;
+            status: hono_utils_http_status.StatusCode;
+        };
+    };
 }, string>;
 
 declare class InMemoryAgentRunner extends AgentRunner {
@@ -173,12 +333,90 @@ declare class InMemoryAgentRunner extends AgentRunner {
     connect(request: AgentRunnerConnectRequest): Observable<BaseEvent>;
     isRunning(request: AgentRunnerIsRunningRequest): Promise<boolean>;
     stop(request: AgentRunnerStopRequest): Promise<boolean | undefined>;
+    listThreads(request: AgentRunnerListThreadsRequest): Promise<AgentRunnerListThreadsResponse>;
+    getThreadMetadata(threadId: string, scope?: {
+        resourceId: string | string[];
+    } | null): Promise<ThreadMetadata | null>;
+    deleteThread(threadId: string, scope?: {
+        resourceId: string | string[];
+    } | null): Promise<void>;
+    /**
+     * Clear all threads from the global store (for testing purposes only)
+     * @internal
+     */
+    clearAllThreads(): void;
 }
 
-interface FinalizeRunOptions {
-    stopRequested?: boolean;
-    interruptionMessage?: string;
-}
-declare function finalizeRunEvents(events: BaseEvent[], options?: FinalizeRunOptions): BaseEvent[];
+/**
+ * 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 };
+ * }
+ * ```
+ */
+declare function validateResourceIdMatch(clientDeclared: string | string[] | undefined, serverAuthorized: string | string[]): void;
+/**
+ * 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 };
+ * }
+ * ```
+ */
+declare function filterAuthorizedResourceIds(clientDeclared: string | string[] | undefined, serverAuthorized: string | string[]): string | string[];
+/**
+ * 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;
+ *   })
+ * });
+ * ```
+ */
+declare function createStrictThreadScopeResolver(getUserId: (request: Request) => Promise<string | string[]>): (context: {
+    request: Request;
+    clientDeclared?: string | string[];
+}) => Promise<ResourceScope>;
+/**
+ * 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);
+ *   })
+ * });
+ * ```
+ */
+declare function createFilteringThreadScopeResolver(getUserResourceIds: (request: Request) => Promise<string[]>): (context: {
+    request: Request;
+    clientDeclared?: string | string[];
+}) => Promise<ResourceScope>;
 
-export { AgentRunner, type AgentRunnerConnectRequest, type AgentRunnerIsRunningRequest, type AgentRunnerRunRequest, type AgentRunnerStopRequest, CopilotRuntime, type CopilotRuntimeOptions, InMemoryAgentRunner, VERSION, createCopilotEndpoint, finalizeRunEvents };
+export { AgentRunner, type AgentRunnerConnectRequest, type AgentRunnerIsRunningRequest, type AgentRunnerListThreadsRequest, type AgentRunnerListThreadsResponse, type AgentRunnerRunRequest, type AgentRunnerStopRequest, CopilotRuntime, type CopilotRuntimeOptions, InMemoryAgentRunner, type ResourceScope, VERSION, createCopilotEndpoint, createFilteringThreadScopeResolver, createStrictThreadScopeResolver, filterAuthorizedResourceIds, validateResourceIdMatch };

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-import { MaybePromise, NonEmptyRecord } from '@copilotkitnext/shared';
+import { MaybePromise, ThreadMetadata, NonEmptyRecord } from '@copilotkitnext/shared';
+export { ThreadMetadata, finalizeRunEvents } from '@copilotkitnext/shared';
 import { AbstractAgent, RunAgentInput, BaseEvent } from '@ag-ui/client';
 import { Observable } from 'rxjs';
 import * as hono_hono_base from 'hono/hono-base';
@@ -47,13 +48,26 @@ declare abstract class TranscriptionService {
     abstract transcribeFile(options: TranscribeFileOptions): Promise<string>;
 }
 
+/**
+ * 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).
+ */
+interface ResourceScope {
+    resourceId: string | string[];
+    properties?: Record<string, any>;
+}
 interface AgentRunnerRunRequest {
     threadId: string;
     agent: AbstractAgent;
     input: RunAgentInput;
+    scope?: ResourceScope | null;
 }
 interface AgentRunnerConnectRequest {
     threadId: string;
+    scope?: ResourceScope | null;
 }
 interface AgentRunnerIsRunningRequest {
     threadId: string;
@@ -61,14 +75,27 @@ interface AgentRunnerIsRunningRequest {
 interface AgentRunnerStopRequest {
     threadId: string;
 }
+interface AgentRunnerListThreadsRequest {
+    scope?: ResourceScope | null;
+    limit?: number;
+    offset?: number;
+}
+interface AgentRunnerListThreadsResponse {
+    threads: ThreadMetadata[];
+    total: number;
+}
 declare abstract class AgentRunner {
     abstract run(request: AgentRunnerRunRequest): Observable<BaseEvent>;
     abstract connect(request: AgentRunnerConnectRequest): Observable<BaseEvent>;
     abstract isRunning(request: AgentRunnerIsRunningRequest): Promise<boolean>;
     abstract stop(request: AgentRunnerStopRequest): Promise<boolean | undefined>;
+    abstract listThreads(request: AgentRunnerListThreadsRequest): Promise<AgentRunnerListThreadsResponse>;
+    abstract getThreadMetadata(threadId: string, scope?: ResourceScope | null): Promise<ThreadMetadata | null>;
+    abstract deleteThread(threadId: string, scope?: ResourceScope | null): Promise<void>;
 }
 
 declare const VERSION: string;
+
 /**
  * Options used to construct a `CopilotRuntime` instance.
  */
@@ -83,17 +110,115 @@ 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<ResourceScope | null>;
+    /**
+     * 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.
  */
 declare 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: (context: {
+        request: Request;
+        clientDeclared?: string | string[];
+    }) => Promise<ResourceScope>;
+    /**
+     * 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 });
+     * ```
+     */
+    static parseClientDeclaredResourceId(request: Request): string | string[] | undefined;
     agents: CopilotRuntimeOptions["agents"];
     transcriptionService: CopilotRuntimeOptions["transcriptionService"];
     beforeRequestMiddleware: CopilotRuntimeOptions["beforeRequestMiddleware"];
     afterRequestMiddleware: CopilotRuntimeOptions["afterRequestMiddleware"];
     runner: AgentRunner;
-    constructor({ agents, transcriptionService, beforeRequestMiddleware, afterRequestMiddleware, runner, }: CopilotRuntimeOptions);
+    resolveThreadsScope: (context: {
+        request: Request;
+        clientDeclared?: string | string[];
+    }) => Promise<ResourceScope | null>;
+    private suppressResourceIdWarning;
+    constructor({ agents, transcriptionService, beforeRequestMiddleware, afterRequestMiddleware, runner, resolveThreadsScope, suppressResourceIdWarning, }: CopilotRuntimeOptions);
+    private logGlobalScopeWarning;
 }
 
 interface CopilotEndpointParams {
@@ -166,6 +291,41 @@ declare function createCopilotEndpoint({ runtime, basePath }: CopilotEndpointPar
             status: hono_utils_http_status.StatusCode;
         };
     };
+} & {
+    [x: `${string}/threads`]: {
+        $get: {
+            input: {};
+            output: {};
+            outputFormat: string;
+            status: hono_utils_http_status.StatusCode;
+        };
+    };
+} & {
+    [x: `${string}/threads/:threadId`]: {
+        $get: {
+            input: {
+                param: {
+                    threadId: string;
+                };
+            };
+            output: {};
+            outputFormat: string;
+            status: hono_utils_http_status.StatusCode;
+        };
+    };
+} & {
+    [x: `${string}/threads/:threadId`]: {
+        $delete: {
+            input: {
+                param: {
+                    threadId: string;
+                };
+            };
+            output: {};
+            outputFormat: string;
+            status: hono_utils_http_status.StatusCode;
+        };
+    };
 }, string>;
 
 declare class InMemoryAgentRunner extends AgentRunner {
@@ -173,12 +333,90 @@ declare class InMemoryAgentRunner extends AgentRunner {
     connect(request: AgentRunnerConnectRequest): Observable<BaseEvent>;
     isRunning(request: AgentRunnerIsRunningRequest): Promise<boolean>;
     stop(request: AgentRunnerStopRequest): Promise<boolean | undefined>;
+    listThreads(request: AgentRunnerListThreadsRequest): Promise<AgentRunnerListThreadsResponse>;
+    getThreadMetadata(threadId: string, scope?: {
+        resourceId: string | string[];
+    } | null): Promise<ThreadMetadata | null>;
+    deleteThread(threadId: string, scope?: {
+        resourceId: string | string[];
+    } | null): Promise<void>;
+    /**
+     * Clear all threads from the global store (for testing purposes only)
+     * @internal
+     */
+    clearAllThreads(): void;
 }
 
-interface FinalizeRunOptions {
-    stopRequested?: boolean;
-    interruptionMessage?: string;
-}
-declare function finalizeRunEvents(events: BaseEvent[], options?: FinalizeRunOptions): BaseEvent[];
+/**
+ * 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 };
+ * }
+ * ```
+ */
+declare function validateResourceIdMatch(clientDeclared: string | string[] | undefined, serverAuthorized: string | string[]): void;
+/**
+ * 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 };
+ * }
+ * ```
+ */
+declare function filterAuthorizedResourceIds(clientDeclared: string | string[] | undefined, serverAuthorized: string | string[]): string | string[];
+/**
+ * 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;
+ *   })
+ * });
+ * ```
+ */
+declare function createStrictThreadScopeResolver(getUserId: (request: Request) => Promise<string | string[]>): (context: {
+    request: Request;
+    clientDeclared?: string | string[];
+}) => Promise<ResourceScope>;
+/**
+ * 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);
+ *   })
+ * });
+ * ```
+ */
+declare function createFilteringThreadScopeResolver(getUserResourceIds: (request: Request) => Promise<string[]>): (context: {
+    request: Request;
+    clientDeclared?: string | string[];
+}) => Promise<ResourceScope>;
 
-export { AgentRunner, type AgentRunnerConnectRequest, type AgentRunnerIsRunningRequest, type AgentRunnerRunRequest, type AgentRunnerStopRequest, CopilotRuntime, type CopilotRuntimeOptions, InMemoryAgentRunner, VERSION, createCopilotEndpoint, finalizeRunEvents };
+export { AgentRunner, type AgentRunnerConnectRequest, type AgentRunnerIsRunningRequest, type AgentRunnerListThreadsRequest, type AgentRunnerListThreadsResponse, type AgentRunnerRunRequest, type AgentRunnerStopRequest, CopilotRuntime, type CopilotRuntimeOptions, InMemoryAgentRunner, type ResourceScope, VERSION, createCopilotEndpoint, createFilteringThreadScopeResolver, createStrictThreadScopeResolver, filterAuthorizedResourceIds, validateResourceIdMatch };