Skip to main content

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​

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​

readonly emitsInvocationEvents: 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​

ExecutionReference

options?​

ProcessOptions

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​

ProcessableStructure

Implementation of​

Processable.describe


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​

Processable.getId


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​

Processable.getName


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​

SkillState


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?​

ProcessOptions

Returns​

Promise<InferSchemaOutput<TOutputSchema>>

Implementation of​

Processable.process


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​

ExecutionContext

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?​

ExecutionStartOptions

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​

Processable.stream


subscribeToAll()​

subscribeToAll(options?): Subscription

Defined in: packages/core/src/baleybot.ts:1563

Subscribe to categorized events from this bot

Parameters​

options?​

SubscribeAllCallbacks

Returns​

Subscription

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​

Processable.subscribeToAll


clearGlobalConfig()​

static clearGlobalConfig(): void

Defined in: packages/core/src/baleybot.ts:357

Returns​

void


create()​

static create<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()​

static getGlobalConfig(): GlobalProviderConfig

Defined in: packages/core/src/baleybot.ts:353

Returns​

GlobalProviderConfig


setApiKey()​

static setApiKey(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​

ProviderName

key​

string

Returns​

void

Example​

Baleybot.setApiKey('anthropic', 'sk-ant-...');
Baleybot.setApiKey('openai', 'sk-...');

setGlobalConfig()​

static setGlobalConfig(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' });