Chat Runtime
chat/runtime
Section titled “chat/runtime”Interfaces
Section titled “Interfaces”BackendInfo
Section titled “BackendInfo”Defined in: chat/runtime.ts:101
Information about a registered backend
Properties
Section titled “Properties”name:
string
Defined in: chat/runtime.ts:103
Backend name (key in backends map)
ChatRuntimeOptions
Section titled “ChatRuntimeOptions”Defined in: chat/runtime.ts:56
Configuration for creating a chat runtime via createChatRuntime()
Properties
Section titled “Properties”backends
Section titled “backends”backends:
Record<string,BackendAdapterFactory>
Defined in: chat/runtime.ts:58
Map of backend name → adapter factory (lazy creation on first use)
context?
Section titled “context?”
optionalcontext:ContextWindowConfig
Defined in: chat/runtime.ts:64
Context window configuration (optional)
defaultBackend
Section titled “defaultBackend”defaultBackend:
string
Defined in: chat/runtime.ts:60
Default backend name (must be a key in backends)
middleware?
Section titled “middleware?”
optionalmiddleware:ChatMiddleware[]
Defined in: chat/runtime.ts:66
Middleware pipeline (optional, applied in order)
onContextTrimmed()?
Section titled “onContextTrimmed()?”
optionalonContextTrimmed: (sessionId,removedMessages) =>void
Defined in: chat/runtime.ts:79
Called when context trimming removes messages. Use for archiving, logging, or analytics.
Parameters
Section titled “Parameters”sessionId
Section titled “sessionId”removedMessages
Section titled “removedMessages”ChatMessage<unknown>[]
Returns
Section titled “Returns”void
retryConfig?
Section titled “retryConfig?”
optionalretryConfig:StreamRetryConfig
Defined in: chat/runtime.ts:68
Retry configuration for pre-stream connection errors
sessionStore
Section titled “sessionStore”sessionStore:
IChatSessionStore
Defined in: chat/runtime.ts:62
Session store for persistence
streamTimeoutMs?
Section titled “streamTimeoutMs?”
optionalstreamTimeoutMs:number
Defined in: chat/runtime.ts:74
Stream inactivity timeout in milliseconds (optional). When set, aborts the stream if no events arrive within this window. Timer resets after each received event.
tools?
Section titled “tools?”
optionaltools:ToolDefinition<unknown>[]
Defined in: chat/runtime.ts:84
Initial tools to register on the runtime.
Equivalent to calling registerTool() for each tool after creation.
IChatClient
Section titled “IChatClient”Defined in: chat/runtime.ts:135
Client-side interface for interacting with a remote chat server. Fully self-contained — no shared base with IChatRuntime. Extends IProviderClient for provider CRUD (ISP). Used by React components and remote clients.
Extends
Section titled “Extends”Type Parameters
Section titled “Type Parameters”TMetadata
Section titled “TMetadata”TMetadata extends Record<string, unknown> = Record<string, unknown>
Type-level convenience for message metadata.
NOT enforced at the storage boundary — session stores always use unknown.
Consumers are responsible for metadata shape consistency.
Properties
Section titled “Properties”activeSessionId
Section titled “activeSessionId”
readonlyactiveSessionId:ChatId|null
Defined in: chat/runtime.ts:150
selectedProviderId
Section titled “selectedProviderId”
readonlyselectedProviderId:string|null
Defined in: chat/runtime.ts:165
status
Section titled “status”
readonlystatus:RuntimeStatus
Defined in: chat/runtime.ts:139
Methods
Section titled “Methods”abort()
Section titled “abort()”abort():
void
Defined in: chat/runtime.ts:161
Returns
Section titled “Returns”void
createProvider()
Section titled “createProvider()”createProvider(
config):Promise<ProviderConfig>
Defined in: chat/runtime.ts:115
Parameters
Section titled “Parameters”config
Section titled “config”Omit<ProviderConfig, "id" | "createdAt">
Returns
Section titled “Returns”Promise<ProviderConfig>
Inherited from
Section titled “Inherited from”IProviderClient.createProvider
createSession()
Section titled “createSession()”createSession(
options):Promise<ChatSession<TMetadata>>
Defined in: chat/runtime.ts:143
Parameters
Section titled “Parameters”options
Section titled “options”CreateSessionOptions<TMetadata>
Returns
Section titled “Returns”Promise<ChatSession<TMetadata>>
deleteProvider()
Section titled “deleteProvider()”deleteProvider(
id):Promise<void>
Defined in: chat/runtime.ts:117
Parameters
Section titled “Parameters”string
Returns
Section titled “Returns”Promise<void>
Inherited from
Section titled “Inherited from”IProviderClient.deleteProvider
deleteSession()
Section titled “deleteSession()”deleteSession(
id):Promise<void>
Defined in: chat/runtime.ts:146
Parameters
Section titled “Parameters”Returns
Section titled “Returns”Promise<void>
dispose()
Section titled “dispose()”dispose():
Promise<void>
Defined in: chat/runtime.ts:140
Returns
Section titled “Returns”Promise<void>
getContextStats()
Section titled “getContextStats()”getContextStats(
sessionId):Promise<ContextStats|null>
Defined in: chat/runtime.ts:176
Parameters
Section titled “Parameters”sessionId
Section titled “sessionId”Returns
Section titled “Returns”Promise<ContextStats | null>
getSession()
Section titled “getSession()”getSession(
id):Promise<ChatSession<TMetadata> |null>
Defined in: chat/runtime.ts:144
Parameters
Section titled “Parameters”Returns
Section titled “Returns”Promise<ChatSession<TMetadata> | null>
listBackends()
Section titled “listBackends()”listBackends():
Promise<BackendInfo[]>
Defined in: chat/runtime.ts:173
Returns
Section titled “Returns”Promise<BackendInfo[]>
listModels()
Section titled “listModels()”listModels():
Promise<ModelInfo[]>
Defined in: chat/runtime.ts:172
Returns
Section titled “Returns”Promise<ModelInfo[]>
listProviders()
Section titled “listProviders()”listProviders():
Promise<ProviderConfig[]>
Defined in: chat/runtime.ts:114
Returns
Section titled “Returns”Promise<ProviderConfig[]>
Inherited from
Section titled “Inherited from”listSessions()
Section titled “listSessions()”listSessions(
options?):Promise<ChatSession<TMetadata>[]>
Defined in: chat/runtime.ts:145
Parameters
Section titled “Parameters”options?
Section titled “options?”Returns
Section titled “Returns”Promise<ChatSession<TMetadata>[]>
onSelectionChange()
Section titled “onSelectionChange()”onSelectionChange(
callback): () =>void
Defined in: chat/runtime.ts:166
Parameters
Section titled “Parameters”callback
Section titled “callback”Returns
Section titled “Returns”():
void
Returns
Section titled “Returns”void
onSessionChange()
Section titled “onSessionChange()”onSessionChange(
callback): () =>void
Defined in: chat/runtime.ts:169
Parameters
Section titled “Parameters”callback
Section titled “callback”() => void
Returns
Section titled “Returns”():
void
Returns
Section titled “Returns”void
selectProvider()
Section titled “selectProvider()”selectProvider(
providerId):void
Defined in: chat/runtime.ts:164
Parameters
Section titled “Parameters”providerId
Section titled “providerId”string
Returns
Section titled “Returns”void
send()
Section titled “send()”send(
sessionId,message,options?):AsyncIterable<ChatEvent>
Defined in: chat/runtime.ts:158
Send a message. Options are optional — the server handler resolves model and backend from provider selection state. Compare with IChatRuntime.send() where RuntimeSendOptions is required.
Parameters
Section titled “Parameters”sessionId
Section titled “sessionId”message
Section titled “message”string
options?
Section titled “options?”Returns
Section titled “Returns”AsyncIterable<ChatEvent>
switchSession()
Section titled “switchSession()”switchSession(
id):Promise<ChatSession<TMetadata>>
Defined in: chat/runtime.ts:149
Parameters
Section titled “Parameters”Returns
Section titled “Returns”Promise<ChatSession<TMetadata>>
updateProvider()
Section titled “updateProvider()”updateProvider(
id,changes):Promise<void>
Defined in: chat/runtime.ts:116
Parameters
Section titled “Parameters”string
changes
Section titled “changes”Partial<Omit<ProviderConfig, "id" | "createdAt">>
Returns
Section titled “Returns”Promise<void>
Inherited from
Section titled “Inherited from”IProviderClient.updateProvider
IChatRuntime
Section titled “IChatRuntime”Defined in: chat/runtime.ts:192
Server-side chat runtime. Fully self-contained — no shared base with IChatClient. Manages backend adapters, tools, middleware, and context trimming. Does NOT include client-facing provider CRUD or selection — those are handled by the server handler layer.
Type Parameters
Section titled “Type Parameters”TMetadata
Section titled “TMetadata”TMetadata extends Record<string, unknown> = Record<string, unknown>
Type-level convenience for message metadata.
NOT enforced at the storage boundary — session stores always use unknown.
Casts in ChatRuntime.createSession()/getSession() are intentionally unsafe
to provide typed access. Consumers are responsible for metadata shape consistency.
Properties
Section titled “Properties”registeredTools
Section titled “registeredTools”
readonlyregisteredTools:ReadonlyMap<string,ToolDefinition<unknown>>
Defined in: chat/runtime.ts:225
status
Section titled “status”
readonlystatus:RuntimeStatus
Defined in: chat/runtime.ts:195
Methods
Section titled “Methods”abort()
Section titled “abort()”abort():
void
Defined in: chat/runtime.ts:213
Returns
Section titled “Returns”void
createSession()
Section titled “createSession()”createSession(
options):Promise<ChatSession<TMetadata>>
Defined in: chat/runtime.ts:199
Parameters
Section titled “Parameters”options
Section titled “options”CreateSessionOptions<TMetadata>
Returns
Section titled “Returns”Promise<ChatSession<TMetadata>>
deleteSession()
Section titled “deleteSession()”deleteSession(
id):Promise<void>
Defined in: chat/runtime.ts:202
Parameters
Section titled “Parameters”Returns
Section titled “Returns”Promise<void>
dispose()
Section titled “dispose()”dispose():
Promise<void>
Defined in: chat/runtime.ts:196
Returns
Section titled “Returns”Promise<void>
getContextStats()
Section titled “getContextStats()”getContextStats(
sessionId):Promise<ContextStats|null>
Defined in: chat/runtime.ts:232
Parameters
Section titled “Parameters”sessionId
Section titled “sessionId”Returns
Section titled “Returns”Promise<ContextStats | null>
getSession()
Section titled “getSession()”getSession(
id):Promise<ChatSession<TMetadata> |null>
Defined in: chat/runtime.ts:200
Parameters
Section titled “Parameters”Returns
Section titled “Returns”Promise<ChatSession<TMetadata> | null>
listBackends()
Section titled “listBackends()”listBackends():
Promise<BackendInfo[]>
Defined in: chat/runtime.ts:220
Returns
Section titled “Returns”Promise<BackendInfo[]>
listModels()
Section titled “listModels()”listModels(
options?):Promise<ModelInfo[]>
Defined in: chat/runtime.ts:219
Parameters
Section titled “Parameters”options?
Section titled “options?”backend?
Section titled “backend?”string
credentials?
Section titled “credentials?”Returns
Section titled “Returns”Promise<ModelInfo[]>
listSessions()
Section titled “listSessions()”listSessions(
options?):Promise<ChatSession<TMetadata>[]>
Defined in: chat/runtime.ts:201
Parameters
Section titled “Parameters”options?
Section titled “options?”Returns
Section titled “Returns”Promise<ChatSession<TMetadata>[]>
onSessionChange()
Section titled “onSessionChange()”onSessionChange(
callback): () =>void
Defined in: chat/runtime.ts:216
Parameters
Section titled “Parameters”callback
Section titled “callback”() => void
Returns
Section titled “Returns”():
void
Returns
Section titled “Returns”void
registerTool()
Section titled “registerTool()”registerTool(
tool):void
Defined in: chat/runtime.ts:223
Parameters
Section titled “Parameters”Returns
Section titled “Returns”void
removeMiddleware()
Section titled “removeMiddleware()”removeMiddleware(
middleware):void
Defined in: chat/runtime.ts:229
Parameters
Section titled “Parameters”middleware
Section titled “middleware”Returns
Section titled “Returns”void
removeTool()
Section titled “removeTool()”removeTool(
name):void
Defined in: chat/runtime.ts:224
Parameters
Section titled “Parameters”string
Returns
Section titled “Returns”void
send()
Section titled “send()”send(
sessionId,message,options):AsyncIterable<ChatEvent>
Defined in: chat/runtime.ts:210
Send a message. RuntimeSendOptions is required on the server — the caller (usually a handler) must supply backend, model, and credentials. Compare with IChatClient.send() where options are optional.
Parameters
Section titled “Parameters”sessionId
Section titled “sessionId”message
Section titled “message”string
options
Section titled “options”Returns
Section titled “Returns”AsyncIterable<ChatEvent>
use(
middleware):void
Defined in: chat/runtime.ts:228
Parameters
Section titled “Parameters”middleware
Section titled “middleware”Returns
Section titled “Returns”void
IProviderClient
Section titled “IProviderClient”Defined in: chat/runtime.ts:113
Provider CRUD operations — separated per Interface Segregation Principle. Implemented by IChatClient (which needs provider management for UI). Not required on IChatRuntime (providers are a handler-layer concern).
Extended by
Section titled “Extended by”Methods
Section titled “Methods”createProvider()
Section titled “createProvider()”createProvider(
config):Promise<ProviderConfig>
Defined in: chat/runtime.ts:115
Parameters
Section titled “Parameters”config
Section titled “config”Omit<ProviderConfig, "id" | "createdAt">
Returns
Section titled “Returns”Promise<ProviderConfig>
deleteProvider()
Section titled “deleteProvider()”deleteProvider(
id):Promise<void>
Defined in: chat/runtime.ts:117
Parameters
Section titled “Parameters”string
Returns
Section titled “Returns”Promise<void>
listProviders()
Section titled “listProviders()”listProviders():
Promise<ProviderConfig[]>
Defined in: chat/runtime.ts:114
Returns
Section titled “Returns”Promise<ProviderConfig[]>
updateProvider()
Section titled “updateProvider()”updateProvider(
id,changes):Promise<void>
Defined in: chat/runtime.ts:116
Parameters
Section titled “Parameters”string
changes
Section titled “changes”Partial<Omit<ProviderConfig, "id" | "createdAt">>
Returns
Section titled “Returns”Promise<void>
StreamRetryConfig
Section titled “StreamRetryConfig”Defined in: chat/runtime.ts:88
Retry configuration for pre-stream failures (renamed to avoid clash with agent-level RetryConfig)
Properties
Section titled “Properties”delayMs
Section titled “delayMs”delayMs:
number
Defined in: chat/runtime.ts:92
Delay between retries in milliseconds
maxAttempts
Section titled “maxAttempts”maxAttempts:
number
Defined in: chat/runtime.ts:90
Maximum number of attempts (default: 1 = no retry)
Type Aliases
Section titled “Type Aliases”BackendAdapterFactory()
Section titled “BackendAdapterFactory()”BackendAdapterFactory = (
credentials) =>IChatBackend|Promise<IChatBackend>
Defined in: chat/runtime.ts:53
Factory function that creates a backend adapter on demand
Parameters
Section titled “Parameters”credentials
Section titled “credentials”Returns
Section titled “Returns”IChatBackend | Promise<IChatBackend>
RetryConfig
Section titled “RetryConfig”RetryConfig =
StreamRetryConfig
Defined in: chat/runtime.ts:96
Deprecated
Section titled “Deprecated”Use StreamRetryConfig
SelectionChangeCallback()
Section titled “SelectionChangeCallback()”SelectionChangeCallback = (
providerId) =>void
Defined in: chat/runtime.ts:123
Callback for provider selection changes
Parameters
Section titled “Parameters”providerId
Section titled “providerId”string | null
Returns
Section titled “Returns”void
Functions
Section titled “Functions”createChatRuntime()
Section titled “createChatRuntime()”createChatRuntime<
TMetadata>(options):IChatRuntime<TMetadata>
Defined in: chat/runtime.ts:920
Create a fully-wired chat runtime from configuration.
Type Parameters
Section titled “Type Parameters”TMetadata
Section titled “TMetadata”TMetadata extends Record<string, unknown> = Record<string, unknown>
Parameters
Section titled “Parameters”options
Section titled “options”Runtime configuration (backends, session store, context, middleware)
Returns
Section titled “Returns”IChatRuntime<TMetadata>
IChatRuntime instance ready to use
Example
Section titled “Example”import { createChatRuntime } from "@witqq/agent-sdk/chat/runtime";import { InMemorySessionStore } from "@witqq/agent-sdk/chat/sessions";
const runtime = createChatRuntime({ backends: { copilot: () => new CopilotAdapter({ agentConfig: { model: "gpt-4" } }), }, defaultBackend: "copilot", sessionStore: new InMemorySessionStore(),});