Session Management

constructor

constructor(
    private storage: IConnectorConfigStorage,
    private encryptionKey: string
  )

Parameters:

• storage: IConnectorConfigStorage
• encryptionKey: string

static create()

Factory that resolves storage from StorageRegistry when no explicit storage is provided.

static create(encryptionKey: string, storage?: IConnectorConfigStorage): ConnectorConfigStore

Parameters:

• encryptionKey: string
• storage: IConnectorConfigStorage | undefined (optional)

Returns: ConnectorConfigStore

save()

Save a connector configuration (secrets are encrypted automatically)

async save(name: string, config: ConnectorConfig): Promise<void>

Parameters:

• name: string
• config: ConnectorConfig

Returns: Promise<void>

get()

Retrieve a connector configuration (secrets are decrypted automatically)

async get(name: string): Promise<ConnectorConfig | null>

Parameters:

• name: string

Returns: Promise<ConnectorConfig | null>

delete()

Delete a connector configuration

async delete(name: string): Promise<boolean>

Parameters:

• name: string

Returns: Promise<boolean>

has()

Check if a connector configuration exists

async has(name: string): Promise<boolean>

Parameters:

• name: string

Returns: Promise<boolean>

list()

List all connector names

async list(): Promise<string[]>

Returns: Promise<string[]>

listAll()

Get all connector configurations (secrets are decrypted automatically)

async listAll(): Promise<ConnectorConfig[]>

Returns: Promise<ConnectorConfig[]>

getMetadata()

Get stored metadata for a connector

async getMetadata(
    name: string
  ): Promise<{ createdAt: number; updatedAt: number; version: number } | null>

Parameters:

• name: string

Returns: Promise<{ createdAt: number; updatedAt: number; version: number; } | null>

saveFromTemplate()

Save a connector created from a vendor template. Handles the full lifecycle: validates, builds auth, encrypts secrets, stores config AND preserves non-secret credentials for round-trip editing.

async saveFromTemplate(
    name: string,
    vendorId: string,
    authTemplateId: string,
    credentials: TemplateCredentials,
    options?: {
      baseURL?: string;
      displayName?: string;
      description?: string;
      defaultModel?: string;
      vendor?: string;
      serviceType?: string;
    },
  ): Promise<ConnectorConfig>

Parameters:

• name: string
• vendorId: string
• authTemplateId: string
• credentials: TemplateCredentials
• options: { baseURL?: string | undefined; displayName?: string | undefined; description?: string | undefined; defaultModel?: string | undefined; vendor?: string | undefined; serviceType?: string | undefined; } | undefined (optional)

Returns: Promise<ConnectorConfig>

updateFromTemplate()

Update a connector that was created from a vendor template. Merges new credentials with existing: non-empty values override, empty values preserve the existing decrypted value ("leave empty to keep"). Same-method authorization-code updates also preserve saved scopes, prompts, token namespaces, PKCE, refresh settings and custom endpoints. Method changes require the new method's own credentials; legacy ambiguity requires replacement.

async updateFromTemplate(
    name: string,
    vendorId: string,
    authTemplateId: string,
    credentials: TemplateCredentials,
    options?: {
      baseURL?: string;
      displayName?: string;
      description?: string;
      defaultModel?: string;
      vendor?: string;
      serviceType?: string;
    },
  ): Promise<ConnectorConfig>

Parameters:

• name: string
• vendorId: string
• authTemplateId: string
• credentials: TemplateCredentials
• options: { baseURL?: string | undefined; displayName?: string | undefined; description?: string | undefined; defaultModel?: string | undefined; vendor?: string | undefined; serviceType?: string | undefined; } | undefined (optional)

Returns: Promise<ConnectorConfig>

constructor

constructor(config: FileAgentDefinitionStorageConfig = {})

Parameters:

• config: FileAgentDefinitionStorageConfig (optional) (default: {})

save()

Save an agent definition

async save(definition: StoredAgentDefinition): Promise<void>

Parameters:

• definition: StoredAgentDefinition

Returns: Promise<void>

load()

Load an agent definition

async load(agentId: string): Promise<StoredAgentDefinition | null>

Parameters:

• agentId: string

Returns: Promise<StoredAgentDefinition | null>

delete()

Delete an agent definition

async delete(agentId: string): Promise<void>

Parameters:

• agentId: string

Returns: Promise<void>

exists()

Check if an agent definition exists

async exists(agentId: string): Promise<boolean>

Parameters:

• agentId: string

Returns: Promise<boolean>

list()

List all agent definitions

async list(options?: AgentDefinitionListOptions): Promise<AgentDefinitionSummary[]>

Parameters:

• options: AgentDefinitionListOptions | undefined (optional)

Returns: Promise<AgentDefinitionSummary[]>

updateMetadata()

Update metadata without loading full definition

async updateMetadata(
    agentId: string,
    metadata: Partial<AgentDefinitionMetadata>
  ): Promise<void>

Parameters:

• agentId: string
• metadata: Partial<AgentDefinitionMetadata>

Returns: Promise<void>

getPath()

Get storage path

getPath(): string

Returns: string

rebuildIndex()

Rebuild the index by scanning all agent directories

async rebuildIndex(): Promise<void>

Returns: Promise<void>

constructor

constructor(config: FileConnectorStorageConfig)

Parameters:

• config: FileConnectorStorageConfig

save()

async save(name: string, stored: StoredConnectorConfig): Promise<void>

Parameters:

• name: string
• stored: StoredConnectorConfig

Returns: Promise<void>

get()

async get(name: string): Promise<StoredConnectorConfig | null>

Parameters:

• name: string

Returns: Promise<StoredConnectorConfig | null>

delete()

async delete(name: string): Promise<boolean>

Parameters:

• name: string

Returns: Promise<boolean>

has()

async has(name: string): Promise<boolean>

Parameters:

• name: string

Returns: Promise<boolean>

list()

async list(): Promise<string[]>

Returns: Promise<string[]>

listAll()

async listAll(): Promise<StoredConnectorConfig[]>

Returns: Promise<StoredConnectorConfig[]>

clear()

Clear all stored configs (useful for testing)

async clear(): Promise<void>

Returns: Promise<void>

constructor

constructor(config: FileContextStorageConfig)

Parameters:

• config: FileContextStorageConfig

save()

Save context state to a session file

async save(
    sessionId: string,
    state: SerializedContextState,
    metadata?: ContextSessionMetadata
  ): Promise<void>

Parameters:

• sessionId: string
• state: SerializedContextState
• metadata: ContextSessionMetadata | undefined (optional)

Returns: Promise<void>

load()

Load context state from a session file

async load(sessionId: string): Promise<StoredContextSession | null>

Parameters:

• sessionId: string

Returns: Promise<StoredContextSession | null>

delete()

Delete a session

async delete(sessionId: string): Promise<void>

Parameters:

• sessionId: string

Returns: Promise<void>

exists()

Check if a session exists

async exists(sessionId: string): Promise<boolean>

Parameters:

• sessionId: string

Returns: Promise<boolean>

list()

List all sessions (summaries only)

async list(options?: ContextStorageListOptions): Promise<ContextSessionSummary[]>

Parameters:

• options: ContextStorageListOptions | undefined (optional)

Returns: Promise<ContextSessionSummary[]>

updateMetadata()

Update session metadata without loading full state

async updateMetadata(
    sessionId: string,
    metadata: Partial<ContextSessionMetadata>
  ): Promise<void>

Parameters:

• sessionId: string
• metadata: Partial<ContextSessionMetadata>

Returns: Promise<void>

getPath()

Get the storage path (for display/debugging)

getPath(): string

Returns: string

getLocation()

Get a human-readable storage location string (for display/debugging)

getLocation(): string

Returns: string

getAgentId()

Get the agent ID

getAgentId(): string

Returns: string

rebuildIndex()

Rebuild the index by scanning all session files Useful for recovery or migration

async rebuildIndex(): Promise<void>

Returns: Promise<void>

constructor

constructor(config?: FileCorrelationStorageConfig)

Parameters:

• config: FileCorrelationStorageConfig | undefined (optional)

save()

async save(correlationId: string, ref: SessionRef): Promise<void>

Parameters:

• correlationId: string
• ref: SessionRef

Returns: Promise<void>

resolve()

async resolve(correlationId: string): Promise<SessionRef | null>

Parameters:

• correlationId: string

Returns: Promise<SessionRef | null>

delete()

async delete(correlationId: string): Promise<void>

Parameters:

• correlationId: string

Returns: Promise<void>

exists()

async exists(correlationId: string): Promise<boolean>

Parameters:

• correlationId: string

Returns: Promise<boolean>

listBySession()

async listBySession(sessionId: string): Promise<string[]>

Parameters:

• sessionId: string

Returns: Promise<string[]>

listByAgent()

async listByAgent(agentId: string): Promise<CorrelationSummary[]>

Parameters:

• agentId: string

Returns: Promise<CorrelationSummary[]>

pruneExpired()

async pruneExpired(): Promise<number>

Returns: Promise<number>

getPath()

getPath(): string

Returns: string

constructor

constructor(config: FileCustomToolStorageConfig = {})

Parameters:

• config: FileCustomToolStorageConfig (optional) (default: {})

save()

Save a custom tool definition

async save(userId: string | undefined, definition: CustomToolDefinition): Promise<void>

Parameters:

• userId: string | undefined
• definition: CustomToolDefinition

Returns: Promise<void>

load()

Load a custom tool definition by name

async load(userId: string | undefined, name: string): Promise<CustomToolDefinition | null>

Parameters:

• userId: string | undefined
• name: string

Returns: Promise<CustomToolDefinition | null>

delete()

Delete a custom tool definition

async delete(userId: string | undefined, name: string): Promise<void>

Parameters:

• userId: string | undefined
• name: string

Returns: Promise<void>

exists()

Check if a custom tool exists

async exists(userId: string | undefined, name: string): Promise<boolean>

Parameters:

• userId: string | undefined
• name: string

Returns: Promise<boolean>

list()

List custom tools (summaries only)

async list(userId: string | undefined, options?: CustomToolListOptions): Promise<CustomToolSummary[]>

Parameters:

• userId: string | undefined
• options: CustomToolListOptions | undefined (optional)

Returns: Promise<CustomToolSummary[]>

updateMetadata()

Update metadata without loading full definition

async updateMetadata(userId: string | undefined, name: string, metadata: Record<string, unknown>): Promise<void>

Parameters:

• userId: string | undefined
• name: string
• metadata: Record<string, unknown>

Returns: Promise<void>

getPath()

Get storage path for a specific user

getPath(userId: string | undefined): string

Parameters:

• userId: string | undefined

Returns: string

constructor

constructor(options: FileEvidenceStorageOptions)

Parameters:

• options: FileEvidenceStorageOptions

inventory()

protected async inventory(): Promise<Array<{ id: string; bytes: number }>>

Returns: Promise<{ id: string; bytes: number; }[]>

writeBlob()

protected async writeBlob(id: string, bytes: Buffer): Promise<void>

Parameters:

• id: string
• bytes: Buffer<ArrayBufferLike>

Returns: Promise<void>

readBlob()

protected async readBlob(id: string): Promise<Buffer | null>

Parameters:

• id: string

Returns: Promise<Buffer<ArrayBufferLike> | null>

removeBlob()

protected async removeBlob(id: string): Promise<boolean>

Parameters:

• id: string

Returns: Promise<boolean>

constructor

constructor(sessionsDirectory: string)

Parameters:

• sessionsDirectory: string

append()

Append entries to the journal file.

Uses fs.appendFile which is atomic for small writes on most filesystems. Each entry is serialized as a single JSON line.

async append(sessionId: string, entries: HistoryEntry[]): Promise<void>

Parameters:

• sessionId: string
• entries: HistoryEntry[]

Returns: Promise<void>

replaceLast()

Replace the most recent entry with the same type + turn index.

JSONL is append-friendly rather than update-friendly, so this rewrites the session journal file only for the narrow correction path used by structured-output post-processing.

async replaceLast(
    sessionId: string,
    type: HistoryEntryType,
    turnIndex: number,
    entry: HistoryEntry,
  ): Promise<boolean>

Parameters:

• sessionId: string
• type: HistoryEntryType
• turnIndex: number
• entry: HistoryEntry

Returns: Promise<boolean>

read()

Read history entries with optional filtering and pagination.

For large files, prefer stream() with pagination.

async read(sessionId: string, options?: HistoryReadOptions): Promise<HistoryEntry[]>

Parameters:

• sessionId: string
• options: HistoryReadOptions | undefined (optional)

Returns: Promise<HistoryEntry[]>

count()

Count entries without fully parsing the file.

Counts non-empty lines in the JSONL file.

async count(sessionId: string): Promise<number>

Parameters:

• sessionId: string

Returns: Promise<number>

clear()

Delete the journal file for a session.

async clear(sessionId: string): Promise<void>

Parameters:

• sessionId: string

Returns: Promise<void>

stream()

Stream history entries line-by-line using readline.

Memory-efficient for large histories — only one entry in memory at a time.

async *stream(sessionId: string, options?: HistoryReadOptions): AsyncIterable<HistoryEntry>

Parameters:

• sessionId: string
• options: HistoryReadOptions | undefined (optional)

Returns: AsyncIterable<HistoryEntry>

getLocation()

Get the file path for a session's journal (for debugging).

getLocation(sessionId: string): string

Parameters:

• sessionId: string

Returns: string

constructor

constructor(config?: FileMediaStorageConfig)

Parameters:

• config: FileMediaStorageConfig | undefined (optional)

save()

async save(data: Buffer, metadata: MediaStorageMetadata): Promise<MediaStorageResult>

Parameters:

• data: Buffer<ArrayBufferLike>
• metadata: MediaStorageMetadata

Returns: Promise<MediaStorageResult>

read()

async read(location: string): Promise<Buffer | null>

Parameters:

• location: string

Returns: Promise<Buffer<ArrayBufferLike> | null>

delete()

async delete(location: string): Promise<void>

Parameters:

• location: string

Returns: Promise<void>

exists()

async exists(location: string): Promise<boolean>

Parameters:

• location: string

Returns: Promise<boolean>

list()

async list(options?: MediaStorageListOptions): Promise<MediaStorageEntry[]>

Parameters:

• options: MediaStorageListOptions | undefined (optional)

Returns: Promise<MediaStorageEntry[]>

getPath()

getPath(): string

Returns: string

constructor

constructor(config: FilePersistentInstructionsStorageConfig)

Parameters:

• config: FilePersistentInstructionsStorageConfig

load()

Load instruction entries from file. Falls back to legacy .md file migration if JSON not found.

async load(): Promise<InstructionEntry[] | null>

Returns: Promise<InstructionEntry[] | null>

save()

Save instruction entries to file as JSON. Creates directory if it doesn't exist. Cleans up legacy .md file if present.

async save(entries: InstructionEntry[]): Promise<void>

Parameters:

• entries: InstructionEntry[]

Returns: Promise<void>

delete()

Delete instructions file (and legacy .md if exists)

async delete(): Promise<void>

Returns: Promise<void>

exists()

Check if instructions file exists (JSON or legacy .md)

async exists(): Promise<boolean>

Returns: Promise<boolean>

getPath()

Get the file path (for display/debugging)

getPath(): string

Returns: string

getAgentId()

Get the agent ID

getAgentId(): string

Returns: string

constructor

constructor(config: FileRoutineDefinitionStorageConfig = {})

Parameters:

• config: FileRoutineDefinitionStorageConfig (optional) (default: {})

save()

async save(context: StorageUserContextInput, definition: RoutineDefinition): Promise<void>

Parameters:

• context: StorageUserContextInput
• definition: RoutineDefinition

Returns: Promise<void>

load()

async load(context: StorageUserContextInput, id: string): Promise<RoutineDefinition | null>

Parameters:

• context: StorageUserContextInput
• id: string

Returns: Promise<RoutineDefinition | null>

delete()

async delete(context: StorageUserContextInput, id: string): Promise<void>

Parameters:

• context: StorageUserContextInput
• id: string

Returns: Promise<void>

exists()

async exists(context: StorageUserContextInput, id: string): Promise<boolean>

Parameters:

• context: StorageUserContextInput
• id: string

Returns: Promise<boolean>

list()

async list(context: StorageUserContextInput, options?: {
    tags?: string[];
    search?: string;
    limit?: number;
    offset?: number;
  }): Promise<RoutineSummary[]>

Parameters:

• context: StorageUserContextInput
• options: { tags?: string[] | undefined; search?: string | undefined; limit?: number | undefined; offset?: number | undefined; } | undefined (optional)

Returns: Promise<RoutineSummary[]>

getPath()

getPath(context: StorageUserContextInput): string

Parameters:

• context: StorageUserContextInput

Returns: string

constructor

constructor(config: FileRoutineExecutionStorageConfig = {})

Parameters:

• config: FileRoutineExecutionStorageConfig (optional) (default: {})

insert()

async insert(context: StorageUserContextInput, record: RoutineExecutionRecord): Promise<string>

Parameters:

• context: StorageUserContextInput
• record: RoutineExecutionRecord

Returns: Promise<string>

update()

async update(
    id: string,
    updates: Partial<
      Pick<RoutineExecutionRecord, 'status' | 'progress' | 'error' | 'completedAt' | 'lastActivityAt'>
    >,
  ): Promise<void>

Parameters:

• id: string
• updates: Partial<Pick<RoutineExecutionRecord, "error" | "status" | "progress" | "completedAt" | "lastActivityAt">>

Returns: Promise<void>

pushStep()

async pushStep(id: string, step: RoutineExecutionStep): Promise<void>

Parameters:

• id: string
• step: RoutineExecutionStep

Returns: Promise<void>

updateTask()

async updateTask(id: string, taskName: string, updates: Partial<RoutineTaskSnapshot>): Promise<void>

Parameters:

• id: string
• taskName: string
• updates: Partial<RoutineTaskSnapshot>

Returns: Promise<void>

load()

async load(id: string): Promise<RoutineExecutionRecord | null>

Parameters:

• id: string

Returns: Promise<RoutineExecutionRecord | null>

list()

async list(
    context: StorageUserContextInput,
    options?: {
      routineId?: string;
      status?: RoutineExecutionStatus;
      limit?: number;
      offset?: number;
    },
  ): Promise<RoutineExecutionRecord[]>

Parameters:

• context: StorageUserContextInput
• options: { routineId?: string | undefined; status?: RoutineExecutionStatus | undefined; limit?: number | undefined; offset?: number | undefined; } | undefined (optional)

Returns: Promise<RoutineExecutionRecord[]>

hasRunning()

async hasRunning(context: StorageUserContextInput, routineId: string): Promise<boolean>

Parameters:

• context: StorageUserContextInput
• routineId: string

Returns: Promise<boolean>

getPath()

getPath(context: StorageUserContextInput): string

Parameters:

• context: StorageUserContextInput

Returns: string

constructor

constructor(config: FileStorageConfig)

Parameters:

• config: FileStorageConfig

storeToken()

async storeToken(key: string, token: StoredToken): Promise<void>

Parameters:

• key: string
• token: StoredToken

Returns: Promise<void>

getToken()

async getToken(key: string): Promise<StoredToken | null>

Parameters:

• key: string

Returns: Promise<StoredToken | null>

deleteToken()

async deleteToken(key: string): Promise<void>

Parameters:

• key: string

Returns: Promise<void>

hasToken()

async hasToken(key: string): Promise<boolean>

Parameters:

• key: string

Returns: Promise<boolean>

listKeys()

List all storage keys by decrypting each token file and reading _storageKey. Falls back to returning hashed filenames for tokens stored before multi-account support.

async listKeys(): Promise<string[]>

Returns: Promise<string[]>

listTokens()

List all token keys (for debugging)

async listTokens(): Promise<string[]>

Returns: Promise<string[]>

clearAll()

Clear all tokens

async clearAll(): Promise<void>

Returns: Promise<void>

constructor

constructor(config?: FileUserInfoStorageConfig)

Parameters:

• config: FileUserInfoStorageConfig | undefined (optional)

load()

Load user info entries from file for a specific user

async load(userId: string | undefined): Promise<UserInfoEntry[] | null>

Parameters:

• userId: string | undefined

Returns: Promise<UserInfoEntry[] | null>

save()

Save user info entries to file for a specific user Creates directory if it doesn't exist.

async save(userId: string | undefined, entries: UserInfoEntry[]): Promise<void>

Parameters:

• userId: string | undefined
• entries: UserInfoEntry[]

Returns: Promise<void>

delete()

Delete user info file for a specific user

async delete(userId: string | undefined): Promise<void>

Parameters:

• userId: string | undefined

Returns: Promise<void>

exists()

Check if user info file exists for a specific user

async exists(userId: string | undefined): Promise<boolean>

Parameters:

• userId: string | undefined

Returns: Promise<boolean>

getPath()

Get the file path for a specific user (for display/debugging)

getPath(userId: string | undefined): string

Parameters:

• userId: string | undefined

Returns: string

constructor

constructor(config?: FileUserPermissionRulesStorageConfig)

Parameters:

• config: FileUserPermissionRulesStorageConfig | undefined (optional)

load()

async load(userId: string | undefined): Promise<UserPermissionRule[] | null>

Parameters:

• userId: string | undefined

Returns: Promise<UserPermissionRule[] | null>

save()

async save(userId: string | undefined, rules: UserPermissionRule[]): Promise<void>

Parameters:

• userId: string | undefined
• rules: UserPermissionRule[]

Returns: Promise<void>

delete()

async delete(userId: string | undefined): Promise<void>

Parameters:

• userId: string | undefined

Returns: Promise<void>

exists()

async exists(userId: string | undefined): Promise<boolean>

Parameters:

• userId: string | undefined

Returns: Promise<boolean>

getPath()

getPath(userId: string | undefined): string

Parameters:

• userId: string | undefined

Returns: string

constructor

constructor(options: GoogleLiveSessionOptions)

Parameters:

• options: GoogleLiveSessionOptions

connect()

async connect(): Promise<void>

Returns: Promise<void>

sendClientContent()

sendClientContent(params: Parameters<Session['sendClientContent']>[0]): void

Parameters:

• params: LiveSendClientContentParameters

Returns: void

sendRealtimeInput()

sendRealtimeInput(params: Parameters<Session['sendRealtimeInput']>[0]): void

Parameters:

• params: LiveSendRealtimeInputParameters

Returns: void

sendToolResponse()

sendToolResponse(params: Parameters<Session['sendToolResponse']>[0]): void

Parameters:

• params: LiveSendToolResponseParameters

Returns: void

close()

close(): void

Returns: void

constructor

constructor(options: GrokRealtimeSessionOptions)

Parameters:

• options: GrokRealtimeSessionOptions

updateSession()

override updateSession(
    session: NonNullable<OpenAIRealtimeSessionOptions['session']> | GrokRealtimeSessionConfig,
  ): void

Parameters:

• session: NonNullable<OpenAIRealtimeSessionConfig | OpenAIRealtimeTranscriptionSessionConfig | OpenAIRealtimeTranslationSessionConfig | undefined> | GrokRealtimeSessionConfig

Returns: void

constructor

constructor(options: OpenAILiveSessionOptions)

Parameters:

• options: OpenAILiveSessionOptions

connect()

async connect(session: LiveAPI.SessionConfig): Promise<LiveAPI.SessionResource>

Parameters:

• session: SessionConfig

Returns: Promise<SessionResource>

appendAudio()

appendAudio(audio: Buffer | string, eventId?: string): void

Parameters:

• audio: string | Buffer<ArrayBufferLike>
• eventId: string | undefined (optional)

Returns: void

send()

send(event: LiveAPI.ClientEvent): void

Parameters:

• event: ClientEvent

Returns: void

events()

events(): AsyncIterableIterator<LiveStreamMessage>

Returns: AsyncIterableIterator<LiveStreamMessage>

close()

close(code = 1000, reason = 'OK'): void

Parameters:

• code: number (optional) (default: 1000)
• reason: string (optional) (default: 'OK')

Returns: void

constructor

constructor(options: OpenAIRealtimeAgentSessionOptions)

Parameters:

• options: OpenAIRealtimeAgentSessionOptions

connect()

async connect(options: { signal?: AbortSignal } = {}): Promise<OpenAIRealtimeServerEvent | undefined>

Parameters:

• options: { signal?: AbortSignal | undefined; } (optional) (default: {})

Returns: Promise<OpenAIRealtimeServerEvent | undefined>

appendAudio()

appendAudio(audio: Buffer | string): boolean

Parameters:

• audio: string | Buffer<ArrayBufferLike>

Returns: boolean

commitAudio()

commitAudio(): void

Returns: void

clearAudio()

clearAudio(): void

Returns: void

cancelResponse()

cancelResponse(): void

Returns: void

createResponse()

createResponse(response: Record<string, unknown> = {}): void

Parameters:

• response: Record<string, unknown> (optional) (default: {})

Returns: void

truncateItem()

truncateItem(itemId: string, audioEndMs: number, contentIndex = 0): void

Parameters:

• itemId: string
• audioEndMs: number
• contentIndex: number (optional) (default: 0)

Returns: void

sendText()

async sendText(text: string, response: Record<string, unknown> = {}): Promise<void>

Parameters:

• text: string
• response: Record<string, unknown> (optional) (default: {})

Returns: Promise<void>

sendImage()

async sendImage(imageUrl: string, response: Record<string, unknown> = {}): Promise<void>

Parameters:

• imageUrl: string
• response: Record<string, unknown> (optional) (default: {})

Returns: Promise<void>

getUsage()

getUsage(): OpenAIRealtimeAgentUsage

Returns: OpenAIRealtimeAgentUsage

handleServerEvent()

Public for custom transports that cannot expose EventEmitter-style events.

async handleServerEvent(event: OpenAIRealtimeServerEvent): Promise<void>

Parameters:

• event: OpenAIRealtimeServerEvent

Returns: Promise<void>

close()

async close(code = 1000, reason = 'OK'): Promise<void>

Parameters:

• code: number (optional) (default: 1000)
• reason: string (optional) (default: 'OK')

Returns: Promise<void>

on()

on<K extends keyof OpenAIRealtimeAgentSessionEvents>(
    event: K,
    handler: OpenAIRealtimeAgentSessionEvents[K],
  ): this

Parameters:

• event: K
• handler: OpenAIRealtimeAgentSessionEvents[K]

Returns: this

updateSession()

Apply a partial/complete Realtime session update.

updateSession(session: OpenAIRealtimeSessionConfig): void

Parameters:

• session: OpenAIRealtimeSessionConfig

Returns: void

send()

Send an advanced Realtime client event through the configured transport.

send(event: OpenAIRealtimeClientEvent): void

Parameters:

• event: OpenAIRealtimeClientEvent

Returns: void

constructor

constructor(options: OpenAIRealtimeSessionOptions)

Parameters:

• options: OpenAIRealtimeSessionOptions

connect()

async connect(options: OpenAIRealtimeConnectOptions = {}): Promise<OpenAIRealtimeServerEvent>

Parameters:

• options: OpenAIRealtimeConnectOptions (optional) (default: {})

Returns: Promise<OpenAIRealtimeServerEvent>

updateSession()

updateSession(session: NonNullable<OpenAIRealtimeSessionOptions['session']>): void

Parameters:

• session: NonNullable<OpenAIRealtimeSessionConfig | OpenAIRealtimeTranscriptionSessionConfig | OpenAIRealtimeTranslationSessionConfig | undefined>

Returns: void

appendAudio()

appendAudio(audio: Buffer | string): boolean

Parameters:

• audio: string | Buffer<ArrayBufferLike>

Returns: boolean

commitAudio()

commitAudio(): void

Returns: void

clearAudio()

clearAudio(): void

Returns: void

createResponse()

createResponse(response: Record<string, unknown> = {}): void

Parameters:

• response: Record<string, unknown> (optional) (default: {})

Returns: void

cancelResponse()

cancelResponse(): void

Returns: void

closeTranslation()

Flush and close a translation stream after handling session.closed.

closeTranslation(): void

Returns: void

sendText()

sendText(text: string): void

Parameters:

• text: string

Returns: void

sendImage()

sendImage(imageUrl: string): void

Parameters:

• imageUrl: string

Returns: void

truncateItem()

truncateItem(itemId: string, audioEndMs: number, contentIndex = 0): void

Parameters:

• itemId: string
• audioEndMs: number
• contentIndex: number (optional) (default: 0)

Returns: void

send()

send(event: OpenAIRealtimeClientEvent): void

Parameters:

• event: OpenAIRealtimeClientEvent

Returns: void

close()

close(code = 1000, reason = 'OK'): void

Parameters:

• code: number (optional) (default: 1000)
• reason: string (optional) (default: 'OK')

Returns: void

on()

on<K extends keyof OpenAIRealtimeSessionEvents>(event: K, handler: OpenAIRealtimeSessionEvents[K]): this

Parameters:

• event: K
• handler: OpenAIRealtimeSessionEvents[K]

Returns: this

constructor

constructor(options: OpenAIResponsesWebSocketSessionOptions)

Parameters:

• options: OpenAIResponsesWebSocketSessionOptions

connect()

async connect(): Promise<void>

Returns: Promise<void>

createResponse()

createResponse(options: OpenAIResponsesCreateEventOptions): void

Parameters:

• options: OpenAIResponsesCreateEventOptions

Returns: void

steer()

Queue additional user input for an active Astra response.

steer(previousResponseId: string, input: ResponseSteerInput): void

Parameters:

• previousResponseId: string
• input: ResponseSteerInput

Returns: void

send()

Send an advanced SDK-typed Responses WebSocket event.

send(event: ResponsesAPI.ResponsesClientEvent): void

Parameters:

• event: ResponsesClientEvent

Returns: void

events()

events(): AsyncIterableIterator<ResponsesStreamMessage>

Returns: AsyncIterableIterator<ResponsesStreamMessage>

close()

close(code = 1000, reason = 'OK'): void

Parameters:

• code: number (optional) (default: 1000)
• reason: string (optional) (default: 'OK')

Returns: void

on()

override on<K extends keyof OpenAIResponsesWebSocketSessionEvents>(
    event: K,
    listener: OpenAIResponsesWebSocketSessionEvents[K],
  ): this

Parameters:

• event: K
• listener: OpenAIResponsesWebSocketSessionEvents[K]

Returns: this

constructor

constructor(config: SessionIngestorPluginConfig)

Parameters:

• config: SessionIngestorPluginConfig

getInstructions()

getInstructions(): string | null

Returns: string | null

getContent()

async getContent(): Promise<string | null>

Returns: Promise<string | null>

getContents()

getContents(): unknown

Returns: unknown

getTokenSize()

getTokenSize(): number

Returns: number

getInstructionsTokenSize()

getInstructionsTokenSize(): number

Returns: number

isCompactable()

isCompactable(): boolean

Returns: boolean

compact()

async compact(_targetTokensToFree: number): Promise<number>

Parameters:

• _targetTokensToFree: number

Returns: Promise<number>

getTools()

getTools(): ToolFunction[]

Returns: ToolFunction<any, any>[]

destroy()

destroy(): void

Returns: void

getState()

getState(): unknown

Returns: unknown

restoreState()

restoreState(state: unknown): void

Parameters:

• state: unknown

Returns: void

onBeforePrepare()

onBeforePrepare(snapshot: PluginPrepareSnapshot): void

Parameters:

• snapshot: PluginPrepareSnapshot

Returns: void

waitForIngest()

Await the current in-flight ingestion, if any. Used by tests to deterministically wait.

async waitForIngest(): Promise<void>

Returns: Promise<void>

flush()

Force-ingest any pending messages and await completion — the graceful- shutdown escape hatch. Bypasses minBatchMessages; uses the most recent onBeforePrepare snapshot as the source (so callers should ensure AgentContextNextGen.prepare() has fired at least once after the last message was added — typically that happens naturally during the last agent turn).

Contract: hosts should call await plugin.flush() before disposing of the plugin (on DDP disconnect, /back, SIGINT, etc.) to guarantee the final batch is persisted. destroy() does NOT await — it only flips the destroyed flag and releases the LLM agent.

Safe to call multiple times; on a destroyed plugin, this awaits any in-flight ingest but does not start a new one.

Optional snapshot override: callers that have already built a fresh PluginPrepareSnapshot (e.g. via another plugin's hook) can pass it in directly and skip the stored-snapshot path.

async flush(snapshot?: PluginPrepareSnapshot): Promise<void>

Parameters:

• snapshot: PluginPrepareSnapshot | undefined (optional)

Returns: Promise<void>

getLastIngestedMessageId()

Id of the last message we've ingested. null before any ingest.

getLastIngestedMessageId(): string | null

Returns: string | null

isDisabled()

Whether bootstrap encountered a foreign-owned entity and disabled the plugin.

isDisabled(): boolean

Returns: boolean

constructor

constructor(
    callInfo: IncomingCallInfo,
    direction: CallDirection = 'inbound',
  )

Parameters:

• callInfo: IncomingCallInfo
• direction: CallDirection (optional) (default: 'inbound')

transition()

Transition to a new state. Throws if the transition is invalid.

transition(newState: SessionState): void

Parameters:

• newState: SessionState

Returns: void

incrementTurns()

Increment the turn counter (called after each agent response completes)

incrementTurns(): void

Returns: void

addSttTime()

addSttTime(ms: number): void

Parameters:

• ms: number

Returns: void

addTtsTime()

addTtsTime(ms: number): void

Parameters:

• ms: number

Returns: void

addAgentTime()

addAgentTime(ms: number): void

Parameters:

• ms: number

Returns: void

createAgent()

Create and assign the agent for this call session.

createAgent(config: AgentConfig): Agent

Parameters:

• config: AgentConfig

Returns: Agent

assignAgent()

Assign a factory-created Agent. VoiceSession assumes ownership and destroys it on end.

assignAgent(agent: Agent): Agent

Parameters:

• agent: Agent

Returns: Agent

setPipeline()

Assign the voice pipeline for this call session.

setPipeline(pipeline: IVoicePipeline): void

Parameters:

• pipeline: IVoicePipeline

Returns: void

setMaxDuration()

Set a maximum call duration timer. When it fires, the session transitions to 'ending'.

setMaxDuration(seconds: number): void

Parameters:

• seconds: number

Returns: void

getInfo()

Get a read-only snapshot of the session state.

getInfo(): VoiceSessionInfo

Returns: VoiceSessionInfo

setEndReason()

Set the reason the call ended (before calling end()).

setEndReason(reason: CallEndReason): void

Parameters:

• reason: CallEndReason

Returns: void

getSummary()

Get the call summary. Only meaningful after the session has ended.

getSummary(): CallSummary

Returns: CallSummary

end()

End the session and clean up all resources.

async end(reason?: CallEndReason): Promise<CallSummary>

Parameters:

• reason: CallEndReason | undefined (optional)

Returns: Promise<CallSummary>

input?: Omit<RealtimeAudioInput, 'format'> & { format?: GrokRealtimeAudioFormat };
output?: Omit<RealtimeAudioOutput, 'format'> & { format?: GrokRealtimeAudioFormat };

};` | - |

request: OpenAIRealtimeMCPApprovalRequest,
decision: OpenAIRealtimeMCPApprovalDecision,

) => void;| - | |'mcp:tools'|'mcp:tools': (event: OpenAIRealtimeServerEvent) => void;| - | |'mcp:call'|'mcp:call': (event: OpenAIRealtimeServerEvent) => void;| - | |usage|usage: (usage: OpenAIRealtimeAgentUsage) => void;| - | |'rate_limits'|'rate_limits': (rateLimits: unknown) => void;| - | |'session:expiring'|'session:expiring': () => void;| - | |backpressure|backpressure: (info: { bufferedAmount: number; limit: number }) => void;| - | |error|error: (error: Error) => void;| - | |close|close: (code: number, reason: string) => void;` | - |

options: ConstructorParameters<typeof OpenAIRealtimeSession>[0],

) => OpenAIRealtimeSession;| Factory used when a custom WebSocket implementation is required. | |safetyIdentifier?|safetyIdentifier?: string;| - | |contextSync?|contextSync?: 'per_turn' | 'initial';|per_turnrefreshes plugin/memory instructions before every model response and therefore manages response.create itself.initialkeeps server VAD's automatic response behavior. Default:per_turn. | | approveMCP?|approveMCP?: ( request: OpenAIRealtimeMCPApprovalRequest, ) => Promise<OpenAIRealtimeMCPApprovalDecision> | OpenAIRealtimeMCPApprovalDecision;| Called for provider-hosted MCP tools. Missing handlers reject approval requests. | |sessionExpiryWarningMs?|sessionExpiryWarningMs?: number;| Emit session:expiring before OpenAI's hard 60-minute limit. Default: 55 minutes. | |sessionUpdateTimeoutMs?|sessionUpdateTimeoutMs?: number;| Maximum time to wait for OpenAI to acknowledge a session update. Default: 10 seconds. | |toolDrainTimeoutMs?|toolDrainTimeoutMs?: number;` | Maximum time to drain active local tools during shutdown. Default: 5 seconds. |

connect()?

connect?(options?: { signal?: AbortSignal }): Promise<OpenAIRealtimeServerEvent>;

Parameters:

• options: { signal?: AbortSignal | undefined; } | undefined (optional)

Returns: Promise<OpenAIRealtimeServerEvent>

updateSession()?

updateSession?(session: OpenAIRealtimeSessionConfig): void;

Parameters:

• session: OpenAIRealtimeSessionConfig

Returns: void

appendAudio()?

appendAudio?(audio: Buffer | string): boolean;

Parameters:

• audio: string | Buffer<ArrayBufferLike>

Returns: boolean

send()

send(event: OpenAIRealtimeClientEvent): void;

Parameters:

• event: OpenAIRealtimeClientEvent

Returns: void

close()

close(code?: number, reason?: string): void;

Parameters:

• code: number | undefined (optional)
• reason: string | undefined (optional)

Returns: void

on()

on(event: 'event', handler: (event: OpenAIRealtimeServerEvent) => void): unknown;

Parameters:

• event: "event"
• handler: (event: OpenAIRealtimeServerEvent) => void

Returns: unknown

on()

on(event: 'audio', handler: (audio: Buffer) => void): unknown;

Parameters:

• event: "audio"
• handler: (audio: Buffer<ArrayBufferLike>) => void

Returns: unknown

on()

on(event: 'error', handler: (error: Error) => void): unknown;

Parameters:

• event: "error"
• handler: (error: Error) => void

Returns: unknown

on()

on(event: 'close', handler: (code: number, reason: string) => void): unknown;

Parameters:

• event: "close"
• handler: (code: number, reason: string) => void

Returns: unknown

on()

on(event: 'backpressure', handler: (info: { bufferedAmount: number; limit: number }) => void): unknown;

Parameters:

• event: "backpressure"
• handler: (info: { bufferedAmount: number; limit: number; }) => void

Returns: unknown

off()?

off?(event: string, handler: (...args: any[]) => void): unknown;

Parameters:

• event: string
• handler: (...args: any[]) => void

Returns: unknown

input?: {
  format?: OpenAIRealtimeAudioFormat;
  transport?: 'json' | 'binary';
  noise_reduction?: { type: 'near_field' | 'far_field' } | null;
  transcription?: {
    model?: string;
    language?: string;
    /** xAI speech-to-speech transcription language hint. */
    language_hint?: string;
    /** xAI speech-to-speech transcription vocabulary hints. */
    keyterms?: string[];
    prompt?: string;
  } | null;
  turn_detection?: OpenAIRealtimeTurnDetection;
};
output?: {
  format?: OpenAIRealtimeAudioFormat;
  transport?: 'json' | 'binary';
  voice?: OpenAIRealtimeVoice | { id: string };
  speed?: number;
};

};` | - |

| OpenAIRealtimeTranscriptionSessionConfig
| OpenAIRealtimeTranslationSessionConfig;` | - |

| safetyIdentifier? | safetyIdentifier?: string; | Stable, privacy-preserving end-user identifier sent as a header. | | headers? | headers?: Record<string, string>; | - | | connectTimeoutMs? | connectTimeoutMs?: number; | - | | maxBufferedAmountBytes? | maxBufferedAmountBytes?: number; | Stop accepting audio frames when WebSocket buffering exceeds this size. Default: 1 MiB. Set 0 to disable. | | webSocketFactory? | webSocketFactory?: ( url: string, options: { headers: Record<string, string>; signal: AbortSignal }, ) => Promise<WebSocketLike> | WebSocketLike; | Test/custom-runtime hook. Normal callers should leave this unset. |

input?: {
  format?: OpenAIRealtimeAudioFormat;
  noise_reduction?: { type: 'near_field' | 'far_field' } | null;
  transcription?: {
    model?: 'gpt-live-transcribe' | 'gpt-transcribe' | (string & {});
    language?: string;
    languages?: string[];
    prompt?: string;
    keywords?: string[];
    delay?: 'low' | 'medium' | 'high' | (string & {});
  };
  turn_detection?: OpenAIRealtimeTurnDetection;
};

};| - | |include?|include?: Array<'item.input_audio_transcription.logprobs'>;` | - |

output: {
  language: string;
};

};` | - |

client: OpenAI,
options: {
  headers?: Record<string, string>;
  reconnect?: ResponsesWSReconnectOptions | null;
  maxQueueSize?: number;
},

) => OpenAIResponsesWebSocketTransport;` | Test/custom-runtime hook. Normal Node callers should leave this unset. |

on()

on(event: string, listener: (...args: any[]) => void): unknown;

Parameters:

• event: string
• listener: (...args: any[]) => void

Returns: unknown

send()

send(event: ResponsesAPI.ResponsesClientEvent): void;

Parameters:

• event: ResponsesClientEvent

Returns: void

stream()

stream(): AsyncIterableIterator<ResponsesStreamMessage>;

Returns: AsyncIterableIterator<ResponsesStreamMessage>

close()

close(props?: { code: number; reason: string }): void;

Parameters:

• props: { code: number; reason: string; } | undefined (optional)

Returns: void

inspect()

Pure bounded detached metadata. No model, service, backend or receipt lookup.

inspect(operationId?: string): ReadonlyArray<Readonly<RemoteOutcomeReport>>;

Parameters:

• operationId: string | undefined (optional)

Returns: readonly Readonly<RemoteOutcomeReport>[]

getReceipt()

getReceipt(operationId: string, options?: { signal?: AbortSignal }): Promise<RemoteOutcomeReport>;

Parameters:

• operationId: string
• options: { signal?: AbortSignal | undefined; } | undefined (optional)

Returns: Promise<RemoteOutcomeReport>

cancel()

cancel(operationId: string, options?: { signal?: AbortSignal; reason?: string }): Promise<RemoteOutcomeReport>;

Parameters:

• operationId: string
• options: { signal?: AbortSignal | undefined; reason?: string | undefined; } | undefined (optional)

Returns: Promise<RemoteOutcomeReport>

readEvidence()

readEvidence(reference: EvidenceReference, options?: { offset?: number; limit?: number; signal?: AbortSignal }): Promise<EvidenceChunk | null>;

Parameters:

• reference: EvidenceReference
• options: { offset?: number | undefined; limit?: number | undefined; signal?: AbortSignal | undefined; } | undefined (optional)

Returns: Promise<EvidenceChunk | null>

checkpoint()

New envelope; does not serialize callbacks, live task authority or a workflow cursor.

checkpoint(options?: ExportAgentPackageOptions): OutcomeAgentPackage;

Parameters:

• options: ExportAgentPackageOptions | undefined (optional)

Returns: OutcomeAgentPackage

checkpoint()

Tools-first construction supplies its owning Agent explicitly.

checkpoint(agent: Agent, options?: ExportAgentPackageOptions): OutcomeAgentPackage;

Parameters:

• agent: Agent
• options: ExportAgentPackageOptions | undefined (optional)

Returns: OutcomeAgentPackage

close()

close(): void;

Returns: void

• 'minimal' — only facts the user stated EXPLICITLY. No inference.
• 'normal' — standard guidelines (skip greetings, tool plumbing).
• 'thorough' — capture tentative inferences too (with confidence < 0.7). | | temperature? | temperature?: number; | Sampling temp for the extractor/merger agent. Default 0.2. | | maxOutputTokens? | maxOutputTokens?: number; | Max output tokens per LLM call. Default: undefined — the provider uses the model's own ceiling, which is always the maximum the model can emit. Set explicitly only when cost control on ambient extraction matters more than extraction completeness. See feedback_no_output_limits.md. | | maxTranscriptChars? | maxTranscriptChars?: number; | Maximum characters of transcript sent to the extractor per run. When the backlog exceeds this, older messages are deferred to subsequent hook invocations (not lost — the watermark stays at the last message that fit). Default 1_000_000 (≈ 250 K tokens at 4 chars/token) — fits every current cheap-tier extractor model (Haiku 4.5 / gpt-5-mini / Gemini 2.5 Flash) with substantial headroom. The default is deliberately high so the "defer to next turn" path is a safety net, not a daily occurrence. | | minBatchMessages? | minBatchMessages?: number; | Minimum number of conversation messages (flat count, not user/assistant pairs) that must have accumulated since the last successful ingest for a natural `onBeforePrepare` trigger to fire. Below this threshold the hook short-circuits and defers to the next turn.

Default: 6 (≈ 3 user/assistant pairs). Set to 1 for per-turn ingest.

For guaranteed final ingest at session end, call `await plugin.flush()` before `plugin.destroy()` — `flush` ignores this threshold. | | forbiddenEntityTypes? | forbiddenEntityTypes?: ReadonlyArray<string>; | Entity types this ambient extractor must NEVER mint. When set, the extraction prompt marks those types as host-managed, and mentions of those types are resolved read-only at write time. If no existing entity resolves, the mention stays unresolved and no entity is created. For host- deterministic types — e.g. ICOS populates event exclusively from the calendar pipeline, so chat extraction may reference existing events but must not create them. Omit for no restriction. |

• 'user_message': as a new user message (default)
• 'tool_result': as a tool result | | metadata? | metadata?: Record<string, unknown>; | Application-specific metadata from the SuspendSignal |