Skip to main content

Class: ChatBot<TResult>

Defined in: chat-bot.ts:109

A bot bound to a conversation.

Examples​

Simple user chat

const assistant = Baleybot.create({ ... });
const chat = ChatBot.forUser(assistant);
await chat.send("Hello!");

With custom history (file-based)

const chat = ChatBot.forUser(assistant, {
history: History.file('chat.json')
});

Type Parameters​

TResult​

TResult = JsonValue

Implements​

  • Processable<string, TResult>

Methods​

clearHistory()​

clearHistory(): Promise<void>

Defined in: chat-bot.ts:260

Returns​

Promise<void>


describe()​

describe(): ProcessableStructure

Defined in: chat-bot.ts:246

The bot, as the turns that run it: a chat runs the same bot once per process() call, so its one child is a repeat edge whose runs are turn-1, turn-2, ...

Returns​

ProcessableStructure

Implementation of​

Processable.describe


getHistory()​

getHistory(): History

Defined in: chat-bot.ts:279

For advanced history management, or sharing one history between ChatBots.

Returns​

History


getId()​

getId(): string

Defined in: chat-bot.ts:233

This instance's id, unique within the process for its lifetime and different after a restart.

Returns​

string

Example​

const bot1 = Baleybot.create({ name: 'analyzer' });
const bot2 = Baleybot.create({ name: 'analyzer' });

bot1.getId(); // 'baleybot-1-a3f891'
bot2.getId(); // 'baleybot-2-b4c2d3'

// Same semantic name, different IDs
bot1.getName(); // 'analyzer'
bot2.getName(); // 'analyzer'

Implementation of​

Processable.getId


getMessages()​

getMessages(): Promise<ChatMessage[]>

Defined in: chat-bot.ts:251

The conversation so far, in the form sent to the model.

Returns​

Promise<ChatMessage[]>


getName()​

getName(): string

Defined in: chat-bot.ts:229

What this processable is called. A label, not a key.

Stable across runs, which getId() is not — an id embeds a timestamp and changes on every restart. That is what makes a name safe to print in a log, show on a node, or hand to a merge function.

Not unique. Two bots may both be called 'analyzer', and every unnamed loop() reports 'loop'. Anything that must address exactly one instance uses getId(), or an address — never this.

Never returns an empty string: where no name was configured, the primitive reports its kind.

Returns​

string

Implementation of​

Processable.getName


getSegments()​

getSegments(): StreamSegment[]

Defined in: chat-bot.ts:256

The conversation as stream segments, the canonical UI representation.

Returns​

StreamSegment[]


process()​

process(input, options?): Promise<InferSchemaOutput<TResult>>

Defined in: chat-bot.ts:166

Run one turn. Accepts plain text or multimodal input (files, images, etc.), which passes through to the bot.

A caller that passes conversationHistory keeps the conversation itself (an adapter's per-channel history): the turn neither reads nor records this chat's history.

Parameters​

input​

string | UnifiedMessageInput

options?​

ProcessOptions

Returns​

Promise<InferSchemaOutput<TResult>>

Implementation of​

Processable.process


processSafe()​

processSafe(input, options?): Promise<Result<TResult, Error>>

Defined in: chat-bot.ts:210

process(), with a failure returned as a Result instead of thrown.

Parameters​

input​

string

options?​

ProcessOptions

Returns​

Promise<Result<TResult, Error>>


rewindLastTurn()​

rewindLastTurn(): Promise<void>

Defined in: chat-bot.ts:269

Drop the last turn (its user message and everything after it), so the next process() runs in its place: a retry that does not see the reply it replaces.

Returns​

Promise<void>


send()​

send(message, options?): Promise<TResult>

Defined in: chat-bot.ts:225

Send a message (chat-friendly alias for process)

Parameters​

message​

string | UnifiedMessageInput

options?​

ProcessOptions

Returns​

Promise<TResult>


subscribeToAll()​

subscribeToAll(options?): Subscription

Defined in: chat-bot.ts:237

Subscribe to categorized events from this processable and all nested processables:

  • onStreamEvent: Real-time content streaming (text_delta, structured_output_delta, tool_call_arguments_delta)
  • onProgressUpdate: Status updates (tool_execution_start, tool_call_stream_start, tool_call_stream_complete, reasoning)
  • onComplete: Emitted when each bot finishes processing with final output
  • onError: Error events (error, tool_validation_error)

Callbacks receive both bot ID and name for precise identification:

  • botId: Unique instance identifier (e.g., 'baleybot-1-a3f891')
  • botName: Semantic name (e.g., 'analyzer', 'router', 'processor')

Callbacks run synchronously inside the run they observe. A callback that throws fails that run with its error once every subscriber has heard the notification (see leafEvents).

Parameters​

options?​

SubscribeAllCallbacks

Returns​

Subscription

Examples​

Subscribe to all events

const subscription = pipeline.subscribeToAll({
onStreamEvent(botId, botName, event) {
if (event.type === 'text_delta') {
console.log(`[${botId}] ${botName}:`, event.content);
}
},
onProgressUpdate(botId, botName, event) {
if (event.type === 'tool_execution_start') {
console.log(`${botName} (${botId}) executing ${event.toolName}`);
}
},
onComplete(botId, botName, output) {
console.log(`${botName} completed:`, output);
},
onError(botId, botName, event) {
console.error(`${botName} error:`, event);
}
});

await pipeline.process('input');
subscription.unsubscribe();

Filter specific bots by name or ID

const subscription = pipeline.subscribeToAll({
onStreamEvent(botId, botName, event) {
console.log(`${botName}:`, event);
},
omit: ['chat-step', 'processor-42-8a3f91'] // Filter by name or ID
});

Implementation of​

Processable.subscribeToAll


forUser()​

static forUser<TBot>(agent, options?): ChatBot<InferBotOutput<TBot>>

Defined in: chat-bot.ts:154

Bind a bot to a conversation.

The result type is inferred from the bot's output schema: a bot with a Zod schema answers that schema's type, one without answers string.

Type Parameters​

TBot​

TBot extends Processable<unknown, unknown>

Parameters​

agent​

TBot

The bot that answers each turn (a Baleybot, a pipeline, any Processable)

options?​

ChatBotConfig = {}

History, handlers, name and timestamps (see ChatBotConfig)

Returns​

ChatBot<InferBotOutput<TBot>>

Example​

const assistant = Baleybot.create({
output: Output.object({
schema: z.object({
response: z.string(),
confidence: z.number(),
}),
}),
});

const chat = ChatBot.forUser(assistant, { includeTimestamps: true });
const result = await chat.send("Hello");

result.response; // ✅ string
result.confidence; // ✅ number
// @ts-expect-error
result.invalid; // ❌ Type error!