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()
staticforUser<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!