Chat Server
chat/server
Section titled “chat/server”Classes
Section titled “Classes”AdapterPool
Section titled “AdapterPool”Defined in: chat/server/adapter-pool.ts:48
Lazy adapter pool with concurrent dedup and eviction. Thread-safe: concurrent getAdapter() calls for the same backend share a single creation promise.
Type Parameters
Section titled “Type Parameters”T extends PooledAdapter = PooledAdapter
Constructors
Section titled “Constructors”Constructor
Section titled “Constructor”new AdapterPool<
T>(options):AdapterPool<T>
Defined in: chat/server/adapter-pool.ts:54
Parameters
Section titled “Parameters”options
Section titled “options”Returns
Section titled “Returns”AdapterPool<T>
Accessors
Section titled “Accessors”activeBackends
Section titled “activeBackends”Get Signature
Section titled “Get Signature”get activeBackends():
string[]
Defined in: chat/server/adapter-pool.ts:108
Get all backend names with cached adapters.
Returns
Section titled “Returns”string[]
Methods
Section titled “Methods”dispose()
Section titled “dispose()”dispose():
Promise<void>
Defined in: chat/server/adapter-pool.ts:113
Dispose all cached adapters and mark pool as unusable.
Returns
Section titled “Returns”Promise<void>
evict()
Section titled “evict()”evict(
backend):Promise<void>
Defined in: chat/server/adapter-pool.ts:94
Evict (dispose and remove) the cached adapter for a backend. Use after token rotation to force re-creation on next getAdapter().
Parameters
Section titled “Parameters”backend
Section titled “backend”string
Returns
Section titled “Returns”Promise<void>
getAdapter()
Section titled “getAdapter()”getAdapter(
backend):Promise<T>
Defined in: chat/server/adapter-pool.ts:63
Get or create an adapter for the given backend. Concurrent calls for the same backend share one creation promise. Failed creations are NOT cached — next call retries.
Parameters
Section titled “Parameters”backend
Section titled “backend”string
Returns
Section titled “Returns”Promise<T>
has(
backend):boolean
Defined in: chat/server/adapter-pool.ts:103
Check if a backend has a cached adapter.
Parameters
Section titled “Parameters”backend
Section titled “backend”string
Returns
Section titled “Returns”boolean
BodyParseError
Section titled “BodyParseError”Defined in: chat/server/utils.ts:8
Error thrown by readBody with an HTTP status code
Extends
Section titled “Extends”Error
Constructors
Section titled “Constructors”Constructor
Section titled “Constructor”new BodyParseError(
message,statusCode):BodyParseError
Defined in: chat/server/utils.ts:10
Parameters
Section titled “Parameters”message
Section titled “message”string
statusCode
Section titled “statusCode”number
Returns
Section titled “Returns”Overrides
Section titled “Overrides”Error.constructor
Properties
Section titled “Properties”statusCode
Section titled “statusCode”
readonlystatusCode:number
Defined in: chat/server/utils.ts:9
FileProviderStore
Section titled “FileProviderStore”Defined in: chat/server/provider-store.ts:58
Filesystem-based provider store using JSON files (one per provider)
Implements
Section titled “Implements”Constructors
Section titled “Constructors”Constructor
Section titled “Constructor”new FileProviderStore(
options):FileProviderStore
Defined in: chat/server/provider-store.ts:61
Parameters
Section titled “Parameters”options
Section titled “options”Returns
Section titled “Returns”Methods
Section titled “Methods”create()
Section titled “create()”create(
config):Promise<void>
Defined in: chat/server/provider-store.ts:65
Create a new provider. Generates UUID if id not set on config.
Parameters
Section titled “Parameters”config
Section titled “config”Returns
Section titled “Returns”Promise<void>
Implementation of
Section titled “Implementation of”delete()
Section titled “delete()”delete(
id):Promise<void>
Defined in: chat/server/provider-store.ts:90
Delete a provider by id.
Parameters
Section titled “Parameters”string
Returns
Section titled “Returns”Promise<void>
Implementation of
Section titled “Implementation of”get(
id):Promise<ProviderConfig|null>
Defined in: chat/server/provider-store.ts:72
Get a provider by id. Returns null if not found.
Parameters
Section titled “Parameters”string
Returns
Section titled “Returns”Promise<ProviderConfig | null>
Implementation of
Section titled “Implementation of”list()
Section titled “list()”list():
Promise<ProviderConfig[]>
Defined in: chat/server/provider-store.ts:98
List all providers.
Returns
Section titled “Returns”Promise<ProviderConfig[]>
Implementation of
Section titled “Implementation of”update()
Section titled “update()”update(
id,changes):Promise<void>
Defined in: chat/server/provider-store.ts:81
Update an existing provider. Throws if not found.
Parameters
Section titled “Parameters”string
changes
Section titled “changes”Partial<Omit<ProviderConfig, "id" | "createdAt">>
Returns
Section titled “Returns”Promise<void>
Implementation of
Section titled “Implementation of”FileTokenStore
Section titled “FileTokenStore”Defined in: chat/server/token-store.ts:64
Filesystem-based token store using JSON files (one per provider)
Implements
Section titled “Implements”Constructors
Section titled “Constructors”Constructor
Section titled “Constructor”new FileTokenStore(
options):FileTokenStore
Defined in: chat/server/token-store.ts:67
Parameters
Section titled “Parameters”options
Section titled “options”Returns
Section titled “Returns”Methods
Section titled “Methods”clear()
Section titled “clear()”clear(
provider):Promise<void>
Defined in: chat/server/token-store.ts:85
Remove a specific provider’s token.
Parameters
Section titled “Parameters”provider
Section titled “provider”string
Returns
Section titled “Returns”Promise<void>
Implementation of
Section titled “Implementation of”clearAll()
Section titled “clearAll()”clearAll():
Promise<void>
Defined in: chat/server/token-store.ts:93
Remove all stored tokens.
Returns
Section titled “Returns”Promise<void>
Implementation of
Section titled “Implementation of”list()
Section titled “list()”list():
Promise<string[]>
Defined in: chat/server/token-store.ts:106
List provider names that have saved tokens.
Returns
Section titled “Returns”Promise<string[]>
Implementation of
Section titled “Implementation of”load()
Section titled “load()”load(
provider):Promise<AuthToken|null>
Defined in: chat/server/token-store.ts:76
Load a previously saved token. Returns null if not found.
Parameters
Section titled “Parameters”provider
Section titled “provider”string
Returns
Section titled “Returns”Promise<AuthToken | null>
Implementation of
Section titled “Implementation of”save()
Section titled “save()”save(
provider,token):Promise<void>
Defined in: chat/server/token-store.ts:71
Save a token for a provider. Overwrites if exists.
Parameters
Section titled “Parameters”provider
Section titled “provider”string
Returns
Section titled “Returns”Promise<void>
Implementation of
Section titled “Implementation of”InMemoryProviderStore
Section titled “InMemoryProviderStore”Defined in: chat/server/provider-store.ts:19
In-memory provider store for testing and ephemeral use
Implements
Section titled “Implements”Constructors
Section titled “Constructors”Constructor
Section titled “Constructor”new InMemoryProviderStore():
InMemoryProviderStore
Returns
Section titled “Returns”Methods
Section titled “Methods”create()
Section titled “create()”create(
config):Promise<void>
Defined in: chat/server/provider-store.ts:22
Create a new provider. Generates UUID if id not set on config.
Parameters
Section titled “Parameters”config
Section titled “config”Returns
Section titled “Returns”Promise<void>
Implementation of
Section titled “Implementation of”delete()
Section titled “delete()”delete(
id):Promise<void>
Defined in: chat/server/provider-store.ts:40
Delete a provider by id.
Parameters
Section titled “Parameters”string
Returns
Section titled “Returns”Promise<void>
Implementation of
Section titled “Implementation of”get(
id):Promise<ProviderConfig|null>
Defined in: chat/server/provider-store.ts:27
Get a provider by id. Returns null if not found.
Parameters
Section titled “Parameters”string
Returns
Section titled “Returns”Promise<ProviderConfig | null>
Implementation of
Section titled “Implementation of”list()
Section titled “list()”list():
Promise<ProviderConfig[]>
Defined in: chat/server/provider-store.ts:44
List all providers.
Returns
Section titled “Returns”Promise<ProviderConfig[]>
Implementation of
Section titled “Implementation of”update()
Section titled “update()”update(
id,changes):Promise<void>
Defined in: chat/server/provider-store.ts:32
Update an existing provider. Throws if not found.
Parameters
Section titled “Parameters”string
changes
Section titled “changes”Partial<Omit<ProviderConfig, "id" | "createdAt">>
Returns
Section titled “Returns”Promise<void>
Implementation of
Section titled “Implementation of”InMemoryTokenStore
Section titled “InMemoryTokenStore”Defined in: chat/server/token-store.ts:30
In-memory token store for testing and ephemeral use
Implements
Section titled “Implements”Constructors
Section titled “Constructors”Constructor
Section titled “Constructor”new InMemoryTokenStore():
InMemoryTokenStore
Returns
Section titled “Returns”Methods
Section titled “Methods”clear()
Section titled “clear()”clear(
provider):Promise<void>
Defined in: chat/server/token-store.ts:42
Remove a specific provider’s token.
Parameters
Section titled “Parameters”provider
Section titled “provider”string
Returns
Section titled “Returns”Promise<void>
Implementation of
Section titled “Implementation of”clearAll()
Section titled “clearAll()”clearAll():
Promise<void>
Defined in: chat/server/token-store.ts:46
Remove all stored tokens.
Returns
Section titled “Returns”Promise<void>
Implementation of
Section titled “Implementation of”list()
Section titled “list()”list():
Promise<string[]>
Defined in: chat/server/token-store.ts:50
List provider names that have saved tokens.
Returns
Section titled “Returns”Promise<string[]>
Implementation of
Section titled “Implementation of”load()
Section titled “load()”load(
provider):Promise<AuthToken|null>
Defined in: chat/server/token-store.ts:37
Load a previously saved token. Returns null if not found.
Parameters
Section titled “Parameters”provider
Section titled “provider”string
Returns
Section titled “Returns”Promise<AuthToken | null>
Implementation of
Section titled “Implementation of”save()
Section titled “save()”save(
provider,token):Promise<void>
Defined in: chat/server/token-store.ts:33
Save a token for a provider. Overwrites if exists.
Parameters
Section titled “Parameters”provider
Section titled “provider”string
Returns
Section titled “Returns”Promise<void>
Implementation of
Section titled “Implementation of”ServiceManager
Section titled “ServiceManager”Defined in: chat/server/service-manager.ts:59
Manages IAgentService lifecycle: create, cache, and dispose on re-auth or logout.
Optionally starts background token refresh when refreshFactory is configured.
Constructors
Section titled “Constructors”Constructor
Section titled “Constructor”new ServiceManager(
options):ServiceManager
Defined in: chat/server/service-manager.ts:64
Parameters
Section titled “Parameters”options
Section titled “options”Returns
Section titled “Returns”Accessors
Section titled “Accessors”activeBackends
Section titled “activeBackends”Get Signature
Section titled “Get Signature”get activeBackends():
string[]
Defined in: chat/server/service-manager.ts:126
Get all backend names with active services.
Returns
Section titled “Returns”string[]
Methods
Section titled “Methods”dispose()
Section titled “dispose()”dispose():
Promise<void>
Defined in: chat/server/service-manager.ts:111
Dispose the ServiceManager — stops all refresh managers and disposes all services.
Returns
Section titled “Returns”Promise<void>
getRefreshManager()
Section titled “getRefreshManager()”getRefreshManager(
backend):TokenRefreshManager|undefined
Defined in: chat/server/service-manager.ts:131
Get active refresh manager for a backend (for testing/introspection).
Parameters
Section titled “Parameters”backend
Section titled “backend”string
Returns
Section titled “Returns”TokenRefreshManager | undefined
getService()
Section titled “getService()”getService(
backend):ManagedService|undefined
Defined in: chat/server/service-manager.ts:116
Get cached service for a backend (undefined if not authenticated).
Parameters
Section titled “Parameters”backend
Section titled “backend”string
Returns
Section titled “Returns”ManagedService | undefined
handleAuth()
Section titled “handleAuth()”handleAuth(
backend,token):Promise<ManagedService>
Defined in: chat/server/service-manager.ts:73
Handle auth event: dispose old service (if any) and create new one. If the token is refreshable and refreshFactory is configured, starts a TokenRefreshManager that auto-refreshes and recreates the service.
Parameters
Section titled “Parameters”backend
Section titled “backend”string
Returns
Section titled “Returns”Promise<ManagedService>
handleLogout()
Section titled “handleLogout()”handleLogout():
Promise<void>
Defined in: chat/server/service-manager.ts:96
Handle logout: dispose all services, stop all refresh managers, clear cache.
Returns
Section titled “Returns”Promise<void>
hasService()
Section titled “hasService()”hasService(
backend):boolean
Defined in: chat/server/service-manager.ts:121
Check if a service exists for the given backend.
Parameters
Section titled “Parameters”backend
Section titled “backend”string
Returns
Section titled “Returns”boolean
Interfaces
Section titled “Interfaces”AdapterPoolOptions
Section titled “AdapterPoolOptions”Defined in: chat/server/adapter-pool.ts:39
Configuration for AdapterPool
Type Parameters
Section titled “Type Parameters”T extends PooledAdapter = PooledAdapter
Properties
Section titled “Properties”factory
Section titled “factory”factory:
AdapterFactory<T>
Defined in: chat/server/adapter-pool.ts:41
Factory to create an adapter for a backend. Called lazily on first getAdapter().
AuthHandlerOptions
Section titled “AuthHandlerOptions”Defined in: chat/server/auth-handler.ts:55
Configuration for createAuthHandler
Properties
Section titled “Properties”createClaudeAuth()?
Section titled “createClaudeAuth()?”
optionalcreateClaudeAuth: () =>IClaudeAuth
Defined in: chat/server/auth-handler.ts:61
Factory for creating ClaudeAuth instances
Returns
Section titled “Returns”createCopilotAuth()?
Section titled “createCopilotAuth()?”
optionalcreateCopilotAuth: () =>ICopilotAuth
Defined in: chat/server/auth-handler.ts:59
Factory for creating CopilotAuth instances
Returns
Section titled “Returns”maxBodySize?
Section titled “maxBodySize?”
optionalmaxBodySize:number
Defined in: chat/server/auth-handler.ts:69
Maximum request body size in bytes. Default: 1MB
onAuth?
Section titled “onAuth?”
optionalonAuth:OnAuthCallback
Defined in: chat/server/auth-handler.ts:63
Called after successful authentication for any provider
onLogout()?
Section titled “onLogout()?”
optionalonLogout: () =>void|Promise<void>
Defined in: chat/server/auth-handler.ts:65
Called when dispose/logout is requested
Returns
Section titled “Returns”void | Promise<void>
prefix?
Section titled “prefix?”
optionalprefix:string
Defined in: chat/server/auth-handler.ts:67
Route prefix to strip from URL before matching. Default: ""
tokenStore
Section titled “tokenStore”tokenStore:
ITokenStore
Defined in: chat/server/auth-handler.ts:57
Token storage implementation
ChatHandlerOptions
Section titled “ChatHandlerOptions”Defined in: chat/server/handler.ts:59
Configuration for createChatHandler
Properties
Section titled “Properties”heartbeatMs?
Section titled “heartbeatMs?”
optionalheartbeatMs:number
Defined in: chat/server/handler.ts:65
SSE heartbeat interval in milliseconds. 0 or undefined disables heartbeat.
hooks?
Section titled “hooks?”
optionalhooks:ChatServerHooks
Defined in: chat/server/handler.ts:71
Consolidated server hooks.
maxBodySize?
Section titled “maxBodySize?”
optionalmaxBodySize:number
Defined in: chat/server/handler.ts:63
Maximum request body size in bytes. Default: 1MB (1048576)
prefix?
Section titled “prefix?”
optionalprefix:string
Defined in: chat/server/handler.ts:61
Route prefix to strip from URL before matching. Default: "" (no prefix)
providerStore?
Section titled “providerStore?”
optionalproviderStore:IProviderStore
Defined in: chat/server/handler.ts:67
Optional provider store for provider CRUD routes.
tokenStore?
Section titled “tokenStore?”
optionaltokenStore:ITokenStore
Defined in: chat/server/handler.ts:69
Optional token store for resolveRequestContext in /send.
transportFactory?
Section titled “transportFactory?”
optionaltransportFactory:TransportFactory
Defined in: chat/server/handler.ts:73
Custom transport factory for /send endpoint. Default: SSEChatTransport.
ChatServerHooks
Section titled “ChatServerHooks”Defined in: chat/server/handler.ts:36
Server-side hooks for customizing chat handler behavior. Consolidates filter, guard, and lifecycle callbacks into a single interface.
Methods
Section titled “Methods”filterModels()?
Section titled “filterModels()?”
optionalfilterModels(models):ModelInfo[]
Defined in: chat/server/handler.ts:38
Filter the model list before returning to client.
Parameters
Section titled “Parameters”models
Section titled “models”Returns
Section titled “Returns”onBackendSwitch()?
Section titled “onBackendSwitch()?”
optionalonBackendSwitch(backend):void|Promise<void>
Defined in: chat/server/handler.ts:44
Called before backend switch. Throw to reject.
Parameters
Section titled “Parameters”backend
Section titled “backend”string
Returns
Section titled “Returns”void | Promise<void>
onBeforeSend()?
Section titled “onBeforeSend()?”
optionalonBeforeSend(sessionId,message):void|Promise<void>
Defined in: chat/server/handler.ts:46
Called before sending a message. Throw to reject.
Parameters
Section titled “Parameters”sessionId
Section titled “sessionId”string
message
Section titled “message”string
Returns
Section titled “Returns”void | Promise<void>
onError()?
Section titled “onError()?”
optionalonError(error,context):void
Defined in: chat/server/handler.ts:48
Global error handler for unhandled route errors.
Parameters
Section titled “Parameters”Error
context
Section titled “context”method
Section titled “method”string
string
Returns
Section titled “Returns”void
onModelSwitch()?
Section titled “onModelSwitch()?”
optionalonModelSwitch(model):void|Promise<void>
Defined in: chat/server/handler.ts:40
Validate model selection on /model/switch and /send model override. Throw to reject.
Parameters
Section titled “Parameters”string
Returns
Section titled “Returns”void | Promise<void>
onProviderSwitch()?
Section titled “onProviderSwitch()?”
optionalonProviderSwitch(info):void|Promise<void>
Defined in: chat/server/handler.ts:42
Called before provider switch. Receives providerId and resolved backend name. Throw to reject.
Parameters
Section titled “Parameters”backend
Section titled “backend”string
providerId
Section titled “providerId”string
Returns
Section titled “Returns”void | Promise<void>
ChatServerOptions
Section titled “ChatServerOptions”Defined in: chat/server/chat-server.ts:39
Configuration for createChatServer
Properties
Section titled “Properties”
optionalauth:AuthHandlerOptions
Defined in: chat/server/chat-server.ts:53
Auth handler options. If provided, auth routes are mounted.
authPrefix?
Section titled “authPrefix?”
optionalauthPrefix:string
Defined in: chat/server/chat-server.ts:56
Prefix for auth routes. Default: “/api/auth”
autoCreateProviders?
Section titled “autoCreateProviders?”
optionalautoCreateProviders:boolean|Record<string,string>
Defined in: chat/server/chat-server.ts:91
Auto-create a default provider when a backend authenticates for the first time.
true— uses built-in default models per backendRecord<string, string>— custom backend→model mapping (e.g.{ copilot: "gpt-5-mini" })false/ omitted — disabled
Requires both auth and providers to be configured.
chatHandlerOptions?
Section titled “chatHandlerOptions?”
optionalchatHandlerOptions:Omit<ChatHandlerOptions,"prefix">
Defined in: chat/server/chat-server.ts:74
Chat handler options (maxBodySize, etc.)
chatPrefix?
Section titled “chatPrefix?”
optionalchatPrefix:string
Defined in: chat/server/chat-server.ts:50
Prefix for chat API routes. Default: “/api/chat”
optionalcors:false|CorsOptions
Defined in: chat/server/chat-server.ts:59
CORS options. Pass false to disable CORS. Default: enabled with permissive settings
healthPath?
Section titled “healthPath?”
optionalhealthPath:string|false
Defined in: chat/server/chat-server.ts:80
Path for the health check endpoint. Default: “/api/health”.
Set to false to disable. Returns { ok: true }.
hooks?
Section titled “hooks?”
optionalhooks:ChatServerHooks
Defined in: chat/server/chat-server.ts:47
Server-side hooks for customizing handler behavior.
providerPrefix?
Section titled “providerPrefix?”
optionalproviderPrefix:string
Defined in: chat/server/chat-server.ts:71
Prefix for provider routes. Default: “/api/providers”
providers?
Section titled “providers?”
optionalproviders:ProviderHandlerOptions
Defined in: chat/server/chat-server.ts:68
Provider handler options. If provided, provider routes are mounted.
runtime?
Section titled “runtime?”
optionalruntime:IChatRuntime<Record<string,unknown>>
Defined in: chat/server/chat-server.ts:41
Pre-built runtime instance. Either runtime or runtimeConfig must be provided.
runtimeConfig?
Section titled “runtimeConfig?”
optionalruntimeConfig:ChatRuntimeOptions
Defined in: chat/server/chat-server.ts:44
Config to auto-create a runtime. Used when runtime is not provided.
serviceManager?
Section titled “serviceManager?”
optionalserviceManager:ServiceManager
Defined in: chat/server/chat-server.ts:100
Service lifecycle manager. When provided with auth, automatically wires:
onAuth→serviceManager.handleAuth(backend, token)(creates/caches service)onLogout→serviceManager.handleLogout()(disposes all services)
User’s own onAuth/onLogout callbacks in auth are still called first.
staticDir?
Section titled “staticDir?”
optionalstaticDir:string
Defined in: chat/server/chat-server.ts:62
Directory to serve static files from. Omit to disable static serving.
staticPrefix?
Section titled “staticPrefix?”
optionalstaticPrefix:string
Defined in: chat/server/chat-server.ts:65
Prefix for static file routes. Default: ”/“
CorsOptions
Section titled “CorsOptions”Defined in: chat/server/cors.ts:8
Configuration for CORS middleware
Properties
Section titled “Properties”headers?
Section titled “headers?”
optionalheaders:string[]
Defined in: chat/server/cors.ts:14
Allowed request headers. Default: [“Content-Type”]
maxAge?
Section titled “maxAge?”
optionalmaxAge:number
Defined in: chat/server/cors.ts:16
Max age for preflight cache in seconds. Default: 86400 (24h)
methods?
Section titled “methods?”
optionalmethods:string[]
Defined in: chat/server/cors.ts:12
Allowed HTTP methods. Default: common REST methods
origin?
Section titled “origin?”
optionalorigin:string|string[]
Defined in: chat/server/cors.ts:10
Allowed origins. Default: ”*” (any origin)
FileProviderStoreOptions
Section titled “FileProviderStoreOptions”Defined in: chat/server/provider-store.ts:52
Options for FileProviderStore
Properties
Section titled “Properties”directory
Section titled “directory”directory:
string
Defined in: chat/server/provider-store.ts:54
Directory to store provider JSON files
FileTokenStoreOptions
Section titled “FileTokenStoreOptions”Defined in: chat/server/token-store.ts:58
Options for FileTokenStore
Properties
Section titled “Properties”directory
Section titled “directory”directory:
string
Defined in: chat/server/token-store.ts:60
Directory to store token JSON files. Default: “.tokens” in cwd
HandlerState
Section titled “HandlerState”Defined in: chat/server/routes/types.ts:17
Handler state — intentionally empty after stateless refactor (STAT-01). Preserved as a type for backward compatibility with custom route modules. Model resolution is now fully per-request via resolveRequestContext.
Deprecated
Section titled “Deprecated”Will be removed in next major version.
Properties
Section titled “Properties”currentModel?
Section titled “currentModel?”
optionalcurrentModel:string
Defined in: chat/server/routes/types.ts:19
Deprecated
Section titled “Deprecated”Model is now resolved per-request. This field is never set.
IClaudeAuth
Section titled “IClaudeAuth”Defined in: chat/server/auth-handler.ts:38
Claude auth class interface (matches ClaudeAuth public API)
Methods
Section titled “Methods”startOAuthFlow()
Section titled “startOAuthFlow()”startOAuthFlow(
options?):object
Defined in: chat/server/auth-handler.ts:39
Parameters
Section titled “Parameters”options?
Section titled “options?”redirectUri?
Section titled “redirectUri?”string
scopes?
Section titled “scopes?”string
Returns
Section titled “Returns”object
authorizeUrl
Section titled “authorizeUrl”authorizeUrl:
string
completeAuth()
Section titled “completeAuth()”completeAuth: (
codeOrUrl) =>Promise<ClaudeAuthToken>
Parameters
Section titled “Parameters”codeOrUrl
Section titled “codeOrUrl”string
Returns
Section titled “Returns”Promise<ClaudeAuthToken>
ICopilotAuth
Section titled “ICopilotAuth”Defined in: chat/server/auth-handler.ts:26
Copilot auth class interface (matches CopilotAuth public API)
Methods
Section titled “Methods”startDeviceFlow()
Section titled “startDeviceFlow()”startDeviceFlow(
options?):Promise<{userCode:string;verificationUrl:string;waitForToken: (signal?) =>Promise<CopilotAuthToken>; }>
Defined in: chat/server/auth-handler.ts:27
Parameters
Section titled “Parameters”options?
Section titled “options?”scopes?
Section titled “scopes?”string
signal?
Section titled “signal?”AbortSignal
Returns
Section titled “Returns”Promise<{ userCode: string; verificationUrl: string; waitForToken: (signal?) => Promise<CopilotAuthToken>; }>
ITokenStore
Section titled “ITokenStore”Defined in: chat/server/token-store.ts:12
Token storage interface for server-side token management
Methods
Section titled “Methods”clear()
Section titled “clear()”clear(
provider):Promise<void>
Defined in: chat/server/token-store.ts:18
Remove a specific provider’s token.
Parameters
Section titled “Parameters”provider
Section titled “provider”string
Returns
Section titled “Returns”Promise<void>
clearAll()
Section titled “clearAll()”clearAll():
Promise<void>
Defined in: chat/server/token-store.ts:20
Remove all stored tokens.
Returns
Section titled “Returns”Promise<void>
dispose()?
Section titled “dispose()?”
optionaldispose():Promise<void>
Defined in: chat/server/token-store.ts:24
Release any resources held by this store (optional).
Returns
Section titled “Returns”Promise<void>
list()
Section titled “list()”list():
Promise<string[]>
Defined in: chat/server/token-store.ts:22
List provider names that have saved tokens.
Returns
Section titled “Returns”Promise<string[]>
load()
Section titled “load()”load(
provider):Promise<AuthToken|null>
Defined in: chat/server/token-store.ts:16
Load a previously saved token. Returns null if not found.
Parameters
Section titled “Parameters”provider
Section titled “provider”string
Returns
Section titled “Returns”Promise<AuthToken | null>
save()
Section titled “save()”save(
provider,token):Promise<void>
Defined in: chat/server/token-store.ts:14
Save a token for a provider. Overwrites if exists.
Parameters
Section titled “Parameters”provider
Section titled “provider”string
Returns
Section titled “Returns”Promise<void>
ManagedService
Section titled “ManagedService”Defined in: chat/server/service-manager.ts:28
Minimal IAgentService interface (avoids importing from main package)
Methods
Section titled “Methods”dispose()
Section titled “dispose()”dispose():
void|Promise<void>
Defined in: chat/server/service-manager.ts:29
Returns
Section titled “Returns”void | Promise<void>
PooledAdapter
Section titled “PooledAdapter”Defined in: chat/server/adapter-pool.ts:30
Minimal adapter interface (avoids importing full IChatBackend)
Methods
Section titled “Methods”dispose()
Section titled “dispose()”dispose():
void|Promise<void>
Defined in: chat/server/adapter-pool.ts:31
Returns
Section titled “Returns”void | Promise<void>
ProviderHandlerOptions
Section titled “ProviderHandlerOptions”Defined in: chat/server/provider-handler.ts:20
Configuration for createProviderHandler
Properties
Section titled “Properties”providerStore
Section titled “providerStore”providerStore:
IProviderStore
Defined in: chat/server/provider-handler.ts:22
Provider storage implementation
ReadableRequest
Section titled “ReadableRequest”Defined in: chat/server/handler.ts:20
Minimal readable request interface (node:http IncomingMessage subset)
Properties
Section titled “Properties”method?
Section titled “method?”
readonlyoptionalmethod:string
Defined in: chat/server/handler.ts:21
readonlyoptionalurl:string
Defined in: chat/server/handler.ts:22
Methods
Section titled “Methods”Call Signature
Section titled “Call Signature”on(
event,listener):unknown
Defined in: chat/server/handler.ts:23
Parameters
Section titled “Parameters”"data"
listener
Section titled “listener”(chunk) => void
Returns
Section titled “Returns”unknown
Call Signature
Section titled “Call Signature”on(
event,listener):unknown
Defined in: chat/server/handler.ts:24
Parameters
Section titled “Parameters”"end"
listener
Section titled “listener”() => void
Returns
Section titled “Returns”unknown
RequestContext
Section titled “RequestContext”Defined in: chat/server/request-context.ts:27
Per-request context carrying backend, credentials, and model
Properties
Section titled “Properties”backend
Section titled “backend”backend:
string
Defined in: chat/server/request-context.ts:29
Backend name (e.g. “copilot”, “claude”, “vercel-ai”)
credentials
Section titled “credentials”credentials:
AuthToken
Defined in: chat/server/request-context.ts:31
Resolved authentication token
model:
string
Defined in: chat/server/request-context.ts:33
Model identifier from provider config
provider
Section titled “provider”provider:
ProviderConfig
Defined in: chat/server/request-context.ts:35
Original provider config for reference
RequestContextDeps
Section titled “RequestContextDeps”Defined in: chat/server/request-context.ts:39
Dependencies for context resolution
Properties
Section titled “Properties”providerStore
Section titled “providerStore”providerStore:
IProviderStore
Defined in: chat/server/request-context.ts:41
Provider store to look up provider config
tokenStore
Section titled “tokenStore”tokenStore:
ITokenStore
Defined in: chat/server/request-context.ts:43
Token store to load credentials for the backend
RouteContext
Section titled “RouteContext”Defined in: chat/server/routes/types.ts:25
Shared context passed to every route module.
Properties
Section titled “Properties”heartbeatMs?
Section titled “heartbeatMs?”
readonlyoptionalheartbeatMs:number
Defined in: chat/server/routes/types.ts:28
hooks?
Section titled “hooks?”
readonlyoptionalhooks:ChatServerHooks
Defined in: chat/server/routes/types.ts:29
maxBodySize
Section titled “maxBodySize”
readonlymaxBodySize:number
Defined in: chat/server/routes/types.ts:27
providerStore?
Section titled “providerStore?”
readonlyoptionalproviderStore:IProviderStore
Defined in: chat/server/routes/types.ts:30
runtime
Section titled “runtime”
readonlyruntime:IChatRuntime
Defined in: chat/server/routes/types.ts:26
readonlystate:HandlerState
Defined in: chat/server/routes/types.ts:33
tokenStore?
Section titled “tokenStore?”
readonlyoptionaltokenStore:ITokenStore
Defined in: chat/server/routes/types.ts:31
transportFactory?
Section titled “transportFactory?”
readonlyoptionaltransportFactory:TransportFactory
Defined in: chat/server/routes/types.ts:32
ServiceManagerOptions
Section titled “ServiceManagerOptions”Defined in: chat/server/service-manager.ts:36
Configuration for ServiceManager
Properties
Section titled “Properties”createService()
Section titled “createService()”createService: (
backend,token) =>ManagedService|Promise<ManagedService>
Defined in: chat/server/service-manager.ts:41
Factory to create a service for a backend. Called on every auth event (old service is disposed first).
Parameters
Section titled “Parameters”backend
Section titled “backend”string
Returns
Section titled “Returns”ManagedService | Promise<ManagedService>
onTokenExpired()?
Section titled “onTokenExpired()?”
optionalonTokenExpired: (backend) =>void
Defined in: chat/server/service-manager.ts:52
Called when a token expires (before logout).
Parameters
Section titled “Parameters”backend
Section titled “backend”string
Returns
Section titled “Returns”void
refreshFactory?
Section titled “refreshFactory?”
optionalrefreshFactory:RefreshFactory
Defined in: chat/server/service-manager.ts:48
Optional factory returning a refresh function per backend. If provided and the token has expiresIn, a TokenRefreshManager is started. On refresh → the stored token is updated and the service is recreated. On expiry → handleLogout() for that backend is called.
refreshOptions?
Section titled “refreshOptions?”
optionalrefreshOptions:Partial<Pick<TokenRefreshOptions,"maxRetries"|"refreshThreshold"|"retryDelayMs">>
Defined in: chat/server/service-manager.ts:50
Override TokenRefreshManager options (threshold, retries, etc.)
Type Aliases
Section titled “Type Aliases”AdapterFactory()
Section titled “AdapterFactory()”AdapterFactory<
T> = (backend) =>Promise<T>
Defined in: chat/server/adapter-pool.ts:35
Factory function to create an adapter for a given backend
Type Parameters
Section titled “Type Parameters”T extends PooledAdapter = PooledAdapter
Parameters
Section titled “Parameters”backend
Section titled “backend”string
Returns
Section titled “Returns”Promise<T>
AuthProvider
Section titled “AuthProvider”AuthProvider =
"copilot"|"claude"|"vercel-ai"
Defined in: chat/server/auth-handler.ts:23
Auth provider names recognized by the handler
ChatRuntimeConfig
Section titled “ChatRuntimeConfig”ChatRuntimeConfig =
ChatRuntimeOptions
Defined in: chat/server/chat-server.ts:36
Configuration for auto-creating a ChatRuntime from options. Alternative to providing a pre-built IChatRuntime instance. Uses the same shape as ChatRuntimeOptions from the runtime module.
OnAuthCallback()
Section titled “OnAuthCallback()”OnAuthCallback = (
provider,token) =>void|Promise<void>
Defined in: chat/server/auth-handler.ts:49
Callback invoked after successful authentication
Parameters
Section titled “Parameters”provider
Section titled “provider”Returns
Section titled “Returns”void | Promise<void>
RefreshFactory()
Section titled “RefreshFactory()”RefreshFactory = (
backend) => (token) =>Promise<AuthToken> |undefined
Defined in: chat/server/service-manager.ts:33
Callback for building a token refresh function per backend
Parameters
Section titled “Parameters”backend
Section titled “backend”string
Returns
Section titled “Returns”(token) => Promise<AuthToken> | undefined
RequestHandler()
Section titled “RequestHandler()”RequestHandler = (
req,res) =>Promise<void>
Defined in: chat/server/chat-server.ts:134
Request handler type returned by createChatServer
Parameters
Section titled “Parameters”Returns
Section titled “Returns”Promise<void>
RouteHandler()
Section titled “RouteHandler()”RouteHandler = (
method,path,req,res,ctx) =>Promise<boolean>
Defined in: chat/server/routes/types.ts:40
A route module handler.
Returns true if the request was handled, false to try next module.
Parameters
Section titled “Parameters”method
Section titled “method”string
string
Returns
Section titled “Returns”Promise<boolean>
TransportFactory()
Section titled “TransportFactory()”TransportFactory = (
req,res) =>IChatTransport
Defined in: chat/server/handler.ts:56
Factory for creating a chat transport for a /send request. Return an IChatTransport instance that will receive the event stream. Default: SSEChatTransport.
Parameters
Section titled “Parameters”Returns
Section titled “Returns”Variables
Section titled “Variables”configRoutes
Section titled “configRoutes”
constconfigRoutes:RouteHandler
Defined in: chat/server/routes/config.ts:14
DEFAULT_PROVIDER_MODELS
Section titled “DEFAULT_PROVIDER_MODELS”
constDEFAULT_PROVIDER_MODELS:Record<string,string>
Defined in: chat/server/chat-server.ts:106
Default model per backend for auto-created providers
messageRoutes
Section titled “messageRoutes”
constmessageRoutes:RouteHandler
Defined in: chat/server/routes/messages.ts:18
providerRoutes
Section titled “providerRoutes”
constproviderRoutes:RouteHandler
Defined in: chat/server/routes/providers.ts:17
sessionRoutes
Section titled “sessionRoutes”
constsessionRoutes:RouteHandler
Defined in: chat/server/routes/sessions.ts:15
Functions
Section titled “Functions”corsMiddleware()
Section titled “corsMiddleware()”corsMiddleware(
options?): (req,res) =>boolean
Defined in: chat/server/cors.ts:39
Create a CORS middleware function.
Parameters
Section titled “Parameters”options?
Section titled “options?”Returns
Section titled “Returns”A function that sets CORS headers and handles OPTIONS preflight.
Returns true if the request was fully handled (preflight),
false if the caller should continue processing.
(
req,res):boolean
Parameters
Section titled “Parameters”CorsRequest
CorsResponse
Returns
Section titled “Returns”boolean
createAuthHandler()
Section titled “createAuthHandler()”createAuthHandler(
options): (req,res) =>Promise<void>
Defined in: chat/server/auth-handler.ts:104
Create an HTTP request handler for server-mediated authentication.
Parameters
Section titled “Parameters”options
Section titled “options”Auth handler configuration (token store, auth factories, callbacks)
Returns
Section titled “Returns”Async request handler (req, res) => Promise<void>
(
req,res):Promise<void>
Parameters
Section titled “Parameters”Returns
Section titled “Returns”Promise<void>
Example
Section titled “Example”import { CopilotAuth, ClaudeAuth } from "@witqq/agent-sdk/auth";
const authHandler = createAuthHandler({ tokenStore: new FileTokenStore({ directory: ".tokens" }), createCopilotAuth: () => new CopilotAuth(), createClaudeAuth: () => new ClaudeAuth(), onAuth: (provider, token) => { // Rebuild runtime with new credentials },});createChatHandler()
Section titled “createChatHandler()”createChatHandler(
runtime,options?): (req,res) =>Promise<void>
Defined in: chat/server/handler.ts:94
Create an HTTP request handler that maps RemoteChatClient contract endpoints to IChatRuntime method calls.
Routes are handled by composable route modules (sessions, messages, config, providers). Model state is managed in a shared HandlerState object.
Parameters
Section titled “Parameters”runtime
Section titled “runtime”options?
Section titled “options?”Returns
Section titled “Returns”(
req,res):Promise<void>
Parameters
Section titled “Parameters”Returns
Section titled “Returns”Promise<void>
createChatServer()
Section titled “createChatServer()”createChatServer(
options):RequestHandler
Defined in: chat/server/chat-server.ts:156
Create a combined HTTP request handler that routes to chat, auth, static, or 404.
Parameters
Section titled “Parameters”options
Section titled “options”Server configuration
Returns
Section titled “Returns”Async request handler
Example
Section titled “Example”import http from "node:http";import { createChatServer } from "@witqq/agent-sdk/chat/server";
const handler = createChatServer({ runtime, auth: { tokenStore }, staticDir: "./public",});
http.createServer(handler).listen(3000);createProviderHandler()
Section titled “createProviderHandler()”createProviderHandler(
options): (req,res) =>Promise<void>
Defined in: chat/server/provider-handler.ts:33
Create an HTTP request handler for provider CRUD operations.
Parameters
Section titled “Parameters”options
Section titled “options”Provider handler configuration
Returns
Section titled “Returns”Async request handler (req, res) => Promise<void>
(
req,res):Promise<void>
Parameters
Section titled “Parameters”Returns
Section titled “Returns”Promise<void>
json()
Section titled “json()”json(
res,data,status?):void
Defined in: chat/server/utils.ts:54
Send a JSON response with given status code.
Parameters
Section titled “Parameters”unknown
status?
Section titled “status?”number = 200
Returns
Section titled “Returns”void
readBody()
Section titled “readBody()”readBody(
req,maxSize?):Promise<Record<string,unknown>>
Defined in: chat/server/utils.ts:21
Read and parse JSON request body with size limit. Throws BodyParseError on oversized, malformed, or errored requests.
Parameters
Section titled “Parameters”maxSize?
Section titled “maxSize?”number = 1_048_576
Returns
Section titled “Returns”Promise<Record<string, unknown>>
resolveRequestContext()
Section titled “resolveRequestContext()”resolveRequestContext(
providerId,deps):Promise<RequestContext>
Defined in: chat/server/request-context.ts:56
Resolve a providerId into a full RequestContext.
Flow: providerId → ProviderConfig (from providerStore) → AuthToken (from tokenStore) → RequestContext
Parameters
Section titled “Parameters”providerId
Section titled “providerId”string
Returns
Section titled “Returns”Promise<RequestContext>
Throws
Section titled “Throws”ChatError with PROVIDER_NOT_FOUND if provider doesn’t exist
Throws
Section titled “Throws”ChatError with AUTH_REQUIRED if no token found for the provider’s backend
References
Section titled “References”IProviderStore
Section titled “IProviderStore”Re-exports IProviderStore
ProviderConfig
Section titled “ProviderConfig”Re-exports ProviderConfig
WritableResponse
Section titled “WritableResponse”Re-exports WritableResponse