Variable: AI

const AI: object;

Primary runtime facade for the Robo AI plugin. Provides chat completions, voice orchestration, image generation, and detailed usage tracking through a single cohesive interface. Import this singleton when integrating AI features inside commands, web handlers, or other Robo plugins.

Type declaration

addRestrictChannel()

addRestrictChannel: (channelId) => void;

Adds a channel to the restrict list at runtime, limiting bot responses to only that channel. Initializes the restrict configuration if it doesn't exist.

Parameters

Parameter	Type	Description
channelId	string	Discord channel ID to add to the restrict list.

Returns

void

Remarks

Changes take effect immediately for new messages. Runtime changes are not persisted and will be lost on restart; the config file takes precedence. Restrict list takes precedence over whitelist.

Example

import { AI } from '@robojs/ai'

// Restrict bot to only respond in a specific channel
AI.addRestrictChannel('123456789012345678')

addWhitelistChannel()

addWhitelistChannel: (channelId) => void;

Adds a channel to the whitelist at runtime, enabling mention-free chat in that channel. Initializes the whitelist configuration if it doesn't exist.

Parameters

Parameter	Type	Description
channelId	string	Discord channel ID to add to the whitelist.

Returns

void

Remarks

Changes take effect immediately for new messages. Runtime changes are not persisted and will be lost on restart; the config file takes precedence.

Example

import { AI } from '@robojs/ai'

// Whitelist a channel when a specific event occurs
AI.addWhitelistChannel('123456789012345678')

chat()

chat: (messages, options) => Promise<void>;

Executes a chat completion using the registered engine. Handles typing indicators, task context, tool invocation scheduling, and token limit errors.

Parameters

Parameter	Type	Description
messages	ChatMessage[]	Message history including system prompts and user turns.
options	ChatOptions	Chat execution options including Discord context and callbacks.

Returns

Promise<void>

Resolves when the chat flow has completed and replies (if any) were dispatched.

Remarks

Tool calls are scheduled asynchronously through the tool executor. Token limit errors are surfaced to the caller via onReply to provide user-friendly messaging.

chatSync()

chatSync: (messages, options) => Promise<ChatReply>;

Helper that wraps chat and resolves with the first reply payload.

Parameters

Parameter	Type	Description
messages	ChatMessage[]	Message array provided to chat.
options	Omit<ChatOptions, "onReply">	Chat options excluding onReply.

Returns

Promise<ChatReply>

Resolves with the reply emitted by the engine or rejects on error.

generateImage()

generateImage: (options) => Promise<GenerateImageResult>;

Generates an image by delegating to the configured engine.

Parameters

Parameter	Type	Description
options	GenerateImageOptions	Image prompt and configuration.

Returns

Promise<GenerateImageResult>

Image generation result containing URLs or base64 payloads.

getActiveTasks()

getActiveTasks: (channelId?) => BackgroundTaskSnapshot[];

Retrieves background task snapshots associated with the optional channel.

Parameters

Parameter	Type
channelId?	string

Returns

BackgroundTaskSnapshot[]

getLifetimeUsage()

getLifetimeUsage: (model?) => Promise<Record<string, TokenWindowTotals>>;

Retrieves lifetime token totals aggregated by model.

Parameters

Parameter	Type
model?	string

Returns

Promise<Record<string, TokenWindowTotals>>

getMCPServers()

getMCPServers: () => MCPTool[];

Retrieves configured MCP servers from plugin options, optionally delegating to the engine's getMCPTools() method if available. Returns an empty array if no MCP servers are configured.

Returns

MCPTool[]

Array of MCP tool configurations.

getRestrictChannels()

getRestrictChannels: () => string[];

Returns the current list of restricted channel IDs.

Returns

string[]

Array of restricted channel IDs, or empty array if none are configured.

Remarks

Returns a copy of the array to prevent external mutation.

Example

import { AI } from '@robojs/ai'

// Check current restrict list
const restricted = AI.getRestrictChannels()
console.log('Restricted channels:', restricted)

getUsageSummary()

getUsageSummary: (query?) => Promise<TokenSummaryResult>;

Resolves summary statistics for token usage within the configured ledger windows.

Parameters

Parameter	Type
query?	TokenSummaryQuery

Returns

Promise<TokenSummaryResult>

getVoiceMetrics()

getVoiceMetrics: () => VoiceMetricsSnapshot;

Returns aggregate metrics describing active voice sessions.

Returns

VoiceMetricsSnapshot

getVoiceStatus()

getVoiceStatus: (guildId?) => Promise<object>;

Retrieves voice subsystem status for the optional guild.

Parameters

Parameter	Type
guildId?	string

Returns

Promise<object>

baseConfig

baseConfig: VoiceRuntimeConfig;

guildConfigs

guildConfigs: Record<string, VoiceRuntimeConfig>;

sessions

sessions: object[] = sessionStatuses;

getWhitelistChannels()

getWhitelistChannels: () => string[];

Returns the current list of whitelisted channel IDs.

Returns

string[]

Array of whitelisted channel IDs, or empty array if none are configured.

Remarks

Returns a copy of the array to prevent external mutation.

Example

import { AI } from '@robojs/ai'

// Check current whitelist
const whitelisted = AI.getWhitelistChannels()
console.log('Whitelisted channels:', whitelisted)

isReady()

isReady: () => boolean;

Returns

boolean

offUsageEvent()

offUsageEvent: <T>(event, listener) => void;

Removes a usage event listener from the token ledger.

Type Parameters

Type Parameter
T extends keyof UsageEventPayloads

Parameters

Parameter	Type
event	T
listener	UsageEventListener<T>

Returns

void

offVoiceEvent()

offVoiceEvent: <T>(event, listener) => void;

Removes a previously registered voice event listener.

Type Parameters

Type Parameter
T extends keyof VoiceEventMap

Parameters

Parameter	Type
event	T
listener	(payload) => void

Returns

void

onceUsageEvent()

onceUsageEvent: <T>(event, listener) => void;

Attaches a one-time usage event listener to the token ledger.

Type Parameters

Type Parameter
T extends keyof UsageEventPayloads

Parameters

Parameter	Type
event	T
listener	UsageEventListener<T>

Returns

void

onUsageEvent()

onUsageEvent: <T>(event, listener) => void;

Attaches a usage event listener to the token ledger.

Type Parameters

Type Parameter
T extends keyof UsageEventPayloads

Parameters

Parameter	Type
event	T
listener	UsageEventListener<T>

Returns

void

onVoiceEvent()

onVoiceEvent: <T>(event, listener) => void;

Registers a voice event listener on the shared voice manager.

Type Parameters

Type Parameter
T extends keyof VoiceEventMap

Parameters

Parameter	Type
event	T
listener	(payload) => void

Returns

void

removeRestrictChannel()

removeRestrictChannel: (channelId) => void;

Removes a channel from the restrict list at runtime.

Parameters

Parameter	Type	Description
channelId	string	Discord channel ID to remove from the restrict list.

Returns

void

Remarks

Safe to call even if the channel isn't in the restrict list. Changes take effect immediately for new messages.

Example

import { AI } from '@robojs/ai'

// Remove a channel from restrict list
AI.removeRestrictChannel('123456789012345678')

removeWhitelistChannel()

removeWhitelistChannel: (channelId) => void;

Removes a channel from the whitelist at runtime.

Parameters

Parameter	Type	Description
channelId	string	Discord channel ID to remove from the whitelist.

Returns

void

Remarks

Safe to call even if the channel isn't in the whitelist. Changes take effect immediately for new messages.

Example

import { AI } from '@robojs/ai'

// Remove a channel from whitelist
AI.removeWhitelistChannel('123456789012345678')

setVoiceConfig()

setVoiceConfig: (options) => Promise<void>;

Applies a voice configuration patch either globally or for a specific guild.

Parameters

Parameter	Type
options	SetVoiceConfigOptions

Returns

Promise<void>

startVoice()

startVoice: (options) => Promise<void>;

Starts the shared voice manager in a Discord guild, joining the specified voice channel and configuring transcription playback streams.

Parameters

Parameter	Type	Description
options	StartVoiceOptions	Voice join options including guild and channel identifiers.

Returns

Promise<void>

Throws

OptionalDependencyError Wrapped when the Discord voice dependency is absent.

stopVoice()

stopVoice: (options) => Promise<void>;

Stops the voice manager within the given guild and disconnects from the active channel.

Parameters

Parameter	Type	Description
options	StopVoiceOptions	Guild identifier and optional channel override.

Returns

Promise<void>

Throws

Error When no voice connection exists for the guild.

Examples

import { AI } from '@robojs/ai'

await AI.chat({
  messages: [
    { role: 'system', content: 'Provide concise answers.' },
    { role: 'user', content: 'Summarize the changelog.' }
  ],
  channel,
  member,
  onReply: ({ text }) => channel.send(text)
})

import { AI } from '@robojs/ai'

await AI.startVoice({ guildId: guild.id, channelId: voiceChannel.id })

AI.onVoiceEvent('playback', ({ delta }) => {
  console.log('Streaming voice chunk', delta.timestamp)
})

await AI.stopVoice({ guildId: guild.id })

import { AI } from '@robojs/ai'

const summary = await AI.getUsageSummary({ window: 'day' })
console.log('Prompt tokens today', summary.windowTotals.prompt)

AI.onUsageEvent('usage.limitReached', (event) => {
  console.warn('Token limit exceeded for', event.breach.model)
})

AI.onUsageEvent('usage.recorded', (event) => {
  console.log('Token usage recorded:', event.usage.tokens)
})

Remarks

Engines lazily initialize. Call AI.isReady() before executing intensive workloads or await project startup hooks to guarantee availability.

See

• BaseEngine
• tokenLedger
• ChatOptions
• VoiceSessionStartOptions