Class: Baleybot<TOutputSchema, TTools>
Defined in: packages/core/src/baleybot.ts:248
An agent that answers through a model, with tool calling and structured
output. Without output, its result type is string.
Type Parameters
TOutputSchema
TOutputSchema = undefined
TTools
TTools extends Tools = Record<string, never>
Implements
Processable<string|UnifiedMessageInput,TOutputSchema>
Constructors
Constructor
new Baleybot<
TOutputSchema,TTools>(config):Baleybot<TOutputSchema,TTools>
Defined in: packages/core/src/baleybot.ts:376
Parameters
config
BaleybotConfig<TOutputSchema, TTools>
Returns
Baleybot<TOutputSchema, TTools>
Properties
config
config:
BaleybotConfig<TOutputSchema,TTools>
Defined in: packages/core/src/baleybot.ts:252
emitsInvocationEvents
readonlyemitsInvocationEvents:true=true
Defined in: packages/core/src/baleybot.ts:534
All events from one process() call reach its own options.onToken callback. Enables isolated step events when the same instance runs concurrently. Subscription-only implementations must not overlap observed invocations.
Implementation of
Processable.emitsInvocationEvents
Methods
attach()
attach(
reference,options?):Promise<ExecutionRun<InferSchemaOutput<TOutputSchema>>>
Defined in: packages/core/src/baleybot.ts:1371
Reattach an observer. The executor keeps the original durable input.
Parameters
reference
options?
Returns
Promise<ExecutionRun<InferSchemaOutput<TOutputSchema>>>
clearHistory()
clearHistory():
Promise<void>
Defined in: packages/core/src/baleybot.ts:1684
Start a fresh conversation on the same instance: clears the history (when
keepHistory is enabled) and forgets skills loaded via load_skill.
Returns
Promise<void>
Example
const bot = Baleybot.create({
name: 'assistant',
goal: 'Help users',
keepHistory: true
});
await bot.process('Hello');
await bot.process('Tell me a joke');
// Start fresh conversation
bot.clearHistory();
await bot.process('Hello'); // Bot won't remember previous messages
describe()
describe():
ProcessableStructure
Defined in: packages/core/src/baleybot.ts:1584
A leaf, placed wherever its executor runs, when it has one. It declares what a run's identity reads, what it needs from a place, its family and its history.
Returns
Implementation of
getHistory()
getHistory():
History|undefined
Defined in: packages/core/src/baleybot.ts:1640
The conversation history, when keepHistory is enabled.
Returns
History | undefined
Example
const bot = Baleybot.create({
name: 'assistant',
goal: 'Help users',
keepHistory: true
});
await bot.process('Hello');
await bot.process('How are you?');
const history = bot.getHistory();
if (history) {
const messages = await history.getMessagesForAPI();
console.log('Conversation history:', messages);
}
getId()
getId():
string
Defined in: packages/core/src/baleybot.ts:1567
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
getName()
getName():
string
Defined in: packages/core/src/baleybot.ts:1575
config.name, or the instance id when the name is empty, so unnamed bots
stay distinct instead of sharing one dev-override key.
Returns
string
Implementation of
getSkillState()
getSkillState():
SkillState
Defined in: packages/core/src/baleybot.ts:1651
The skills the model loaded with load_skill and has not unloaded — plain
JSON to store with the conversation. Hand it back through
ProcessOptions.skillState (or restoreSkillState) when a fresh
per-request bot continues the conversation, so what the model loaded stays
loaded. { loaded: [] } when the bot has no skills.
Returns
process()
process(
input,options?):Promise<InferSchemaOutput<TOutputSchema>>
Defined in: packages/core/src/baleybot.ts:1321
A bot with history or skills takes one call at a time: a concurrent call throws.
Parameters
input
string | UnifiedMessageInput
options?
Returns
Promise<InferSchemaOutput<TOutputSchema>>
Implementation of
recordInterruptedTurn()
recordInterruptedTurn(
input,options):Promise<boolean>
Defined in: packages/core/src/baleybot.ts:1613
Record an unfinished checkpointed turn into this bot's history, from its
journal: the person's message (input) and every step the turn completed,
with the steering merged into it.
A call that ends part-way records the turn itself; a call that never got the chance (its instance crashed) leaves only the journal. Call this before a different turn starts while that one is unfinished — the person moved on instead of resuming — so the new turn reads what was already done. It is idempotent: the turn's record is replaced in place under its turn id, and a later resume of the same turn still reads it once.
Returns false (and records nothing) when the turn already finished or is paused for a person — its record reached history then.
Parameters
input
string
options
execution
Returns
Promise<boolean>
restoreSkillState()
restoreSkillState(
state):void
Defined in: packages/core/src/baleybot.ts:1659
Replace the loaded-skill set with a saved getSkillState. Unknown skill names are dropped with a warning. A no-op on a bot without skills.
Parameters
state
SkillState | undefined
Returns
void
start()
start(
input,options?):Promise<ExecutionRun<InferSchemaOutput<TOutputSchema>>>
Defined in: packages/core/src/baleybot.ts:1359
Start durable work without holding the caller open until completion. With an executor, the executor's place owns the run. Without one, the bot runs at the local place, like any other Processable.
Parameters
input
string | UnifiedMessageInput
options?
Returns
Promise<ExecutionRun<InferSchemaOutput<TOutputSchema>>>
stream()
stream(
input,options?):AsyncGenerator<BaleybotStreamEvent>
Defined in: packages/core/src/baleybot.ts:1533
Stream events as an async iterator
Parameters
input
string | UnifiedMessageInput
options?
Omit<ProcessOptions, "onError" | "onToken" | "onComplete">
Returns
AsyncGenerator<BaleybotStreamEvent>
Example
for await (const event of bot.stream('Hello')) {
if (event.type === 'text_delta') {
process.stdout.write(event.content);
}
}
Implementation of
subscribeToAll()
subscribeToAll(
options?):Subscription
Defined in: packages/core/src/baleybot.ts:1563
Subscribe to categorized events from this bot
Parameters
options?
Returns
Example
const subscription = bot.subscribeToAll({
onStreamEvent(botId, botName, event) {
if (event.type === 'text_delta') {
process.stdout.write(event.content);
}
},
onProgressUpdate(botId, botName, event) {
console.log(`${botName}:`, event.type);
},
onComplete(botId, botName, output) {
console.log(`${botName} done:`, output);
}
});
await bot.process('input');
subscription.unsubscribe();
Implementation of
clearGlobalConfig()
staticclearGlobalConfig():void
Defined in: packages/core/src/baleybot.ts:357
Returns
void
create()
staticcreate<TOutputSchema,TTools>(config):Baleybot<TOutputSchema,TTools>
Defined in: packages/core/src/baleybot.ts:327
Create a new Baleybot (static factory method for convenience)
When output is undefined or omitted, the output type is inferred as string.
Type Parameters
TOutputSchema
TOutputSchema = undefined
TTools
TTools extends Tools = Record<string, never>
Parameters
config
BaleybotConfig<TOutputSchema, TTools>
Returns
Baleybot<TOutputSchema, TTools>
Example
// Without model - auto-selects based on available API keys
const bot = Baleybot.create({
name: 'my-bot',
goal: 'Help users'
// No model specified - auto-selects!
});
const result: string = await bot.process('Hello');
// With explicit model
const bot2 = Baleybot.create({
name: 'my-bot',
goal: 'Help users',
model: 'gpt-5.6-luna'
});
const result2: string = await bot2.process('Hello');
// With output - returns typed output
const bot3 = Baleybot.create({
name: 'my-bot',
goal: 'Help users',
model: 'gpt-5.6-luna',
output: Output.object({ schema: z.object({ sentiment: z.string() }) })
});
const result3: { sentiment: string } = await bot3.process('Hello');
getGlobalConfig()
staticgetGlobalConfig():GlobalProviderConfig
Defined in: packages/core/src/baleybot.ts:353
Returns
GlobalProviderConfig
setApiKey()
staticsetApiKey(provider,key):void
Defined in: packages/core/src/baleybot.ts:372
Set API key for a provider
Convenience alias for the most common global config pattern.
Parameters
provider
key
string
Returns
void
Example
Baleybot.setApiKey('anthropic', 'sk-ant-...');
Baleybot.setApiKey('openai', 'sk-...');
setGlobalConfig()
staticsetGlobalConfig(config):void
Defined in: packages/core/src/baleybot.ts:349
Set global provider configuration
Config is merged with instance-level config, with instance config taking priority.
Parameters
config
GlobalProviderConfig
Returns
void
Example
Baleybot.setGlobalConfig({
proxyUrl: '', // Same-origin proxy for all providers
openai: { headers: { 'X-Custom': 'value' } },
});
// Now works without per-model proxyUrl
const bot = new Baleybot({ name: 'bot', goal: 'Help', model: 'gpt-5.6-luna' });