Class: Orchestrator
Defined in: packages/orchestration/src/orchestrator.ts:147
Example
// With in-memory stores (no infrastructure needed)
import { InMemoryTicketStore, InMemoryRunStore } from '@baleybots/orchestration';
const orch = new Orchestrator({
stores: { tickets: new InMemoryTicketStore(), runs: new InMemoryRunStore() },
});
orch.registerAgent({
name: 'coder',
role: 'Software Engineer',
capabilities: ['typescript', 'testing'],
processable: myBot,
});
const ticket = await orch.createTicket({
title: 'Add auth',
description: 'Implement JWT authentication',
tags: ['typescript'],
});
// Option A: manual dispatch
await orch.dispatch(ticket.id, 'coder');
// Option B: automatic scheduling
orch.start();
// Listen to live events
orch.events.on('run.event', ({ runId, event, agentName }) => {
console.log(`[${agentName}] ${event.type}`);
});
Constructors
Constructor
new Orchestrator(
config):Orchestrator
Defined in: packages/orchestration/src/orchestrator.ts:161
Parameters
config
Returns
Orchestrator
Properties
agents
readonlyagents:AgentRegistry
Defined in: packages/orchestration/src/orchestrator.ts:150
costs
readonlycosts:CostTracker
Defined in: packages/orchestration/src/orchestrator.ts:151
events
readonlyevents:EventBus<OrchestrationEventMap>
Defined in: packages/orchestration/src/orchestrator.ts:149
runs
readonlyruns:RunManager
Defined in: packages/orchestration/src/orchestrator.ts:152
scheduler
readonlyscheduler:Scheduler
Defined in: packages/orchestration/src/orchestrator.ts:153
Methods
answer()
answer(
questionId,answer,options?):Promise<{question:HumanQuestion;resume:"pending"|"running"|"failed"|"cancelled"|"paused"|"completed";run:Run; } | {question:HumanQuestion;resume:"host"|"waiting"|"claimed"|"resuming";run?:undefined; }>
Defined in: packages/orchestration/src/orchestrator.ts:210
Accept exactly once. Await auto resume by default; host mode emits only.
Parameters
questionId
string
answer
options?
waitForCompletion?
boolean
Returns
Promise<{ question: HumanQuestion; resume: "pending" | "running" | "failed" | "cancelled" | "paused" | "completed"; run: Run; } | { question: HumanQuestion; resume: "host" | "waiting" | "claimed" | "resuming"; run?: undefined; }>
cancelRun()
cancelRun(
runId):Promise<void>
Defined in: packages/orchestration/src/orchestrator.ts:328
Cancel a run; throws when it is not running (cancelTicket does not).
Parameters
runId
string
Returns
Promise<void>
cancelTicket()
cancelTicket(
ticketId,options?):Promise<Ticket>
Defined in: packages/orchestration/src/orchestrator.ts:341
Cancel a ticket whatever its state. Idempotent: a ticket that already ended is returned as it is.
A running run is aborted, and the run settles its ticket as cancelled (on this instance when it ends; at once when another instance runs it). Otherwise — queued, backlog, or waiting on a paused run — the ticket is settled as cancelled here, fenced to the run it holds.
Parameters
ticketId
string
options?
reason?
string
Returns
Promise<Ticket>
createQuestion()
createQuestion(
ticketId,runId,config):Promise<HumanQuestion>
Defined in: packages/orchestration/src/orchestrator.ts:195
Host-managed questions can outlive the turn that created them.
Parameters
ticketId
string
runId
string
config
addressee?
{ address?: string; kind: "owner" | "third_party"; } = ...
addressee.address?
string = ...
addressee.kind
"owner" | "third_party" = ...
channelHints?
string[] = ...
expiresAt?
number = ...
fields?
({ id: string; label: string; maxLength?: number; required?: boolean; type: "short_text"; } | { id: string; label: string; multiple?: boolean; options: object[]; required?: boolean; type: "choice"; } | { id: string; label: string; required?: boolean; type: "file_reference"; } | { id: string; label: string; required?: boolean; spec: { cancelLabel?: string; confirmLabel?: string; id?: string; kind: "confirm"; metadata?: Record<string, unknown>; prompt: string; } | { id?: string; kind: "text"; maxLength?: number; metadata?: Record<string, unknown>; placeholder?: string; prompt: string; } | { id?: string; kind: "choice"; metadata?: Record<string, unknown>; multiple?: boolean; options: object[]; prompt: string; } | { id?: string; kind: "number"; max: number; metadata?: Record<string, unknown>; min: number; prompt: string; step?: number; } | { accept?: string[]; id?: string; kind: "file"; maxBytes?: number; metadata?: Record<string, unknown>; prompt: string; } | { id?: string; kind: "encrypted"; metadata?: Record<string, unknown>; prompt: string; purpose?: "password" | "secret" | "api_key"; }; type: "core_interrupt"; })[] = ...
question
string = ...
reminderPolicy?
{ afterMs: number; maxReminders: number; } = ...
reminderPolicy.afterMs
number = ...
reminderPolicy.maxReminders
number = ...
resumeMode?
"auto" | "host" = ...
why
string = ...
Returns
Promise<HumanQuestion>
createTicket()
createTicket(
rawConfig):Promise<Ticket>
Defined in: packages/orchestration/src/orchestrator.ts:253
Parameters
rawConfig
Returns
Promise<Ticket>
createTickets()
createTickets(
configs):Promise<Ticket[]>
Defined in: packages/orchestration/src/orchestrator.ts:355
In order, so a ticket can depend on an earlier one in the same call.
Parameters
configs
Returns
Promise<Ticket[]>
deleteTicket()
deleteTicket(
id):Promise<void>
Defined in: packages/orchestration/src/orchestrator.ts:308
Parameters
id
string
Returns
Promise<void>
dispatch()
dispatch(
ticketId,agentName,options?):Promise<Run>
Defined in: packages/orchestration/src/orchestrator.ts:364
Run a ticket on an agent now, bypassing the scheduler. Resolves when the run ends, pauses or yields.
Parameters
ticketId
string
agentName
string
options?
parentRunId?
string
Returns
Promise<Run>
dispatchOnce()
dispatchOnce(
options?):Promise<string[]>
Defined in: packages/orchestration/src/orchestrator.ts:431
One dispatch pass without the heartbeat timer — the serverless entry
point (a cron, a queue consumer). Starts a run for every ready ticket an
agent can take and resolves the ticket ids. With wait, resolves only
once those runs settle (bound them with yieldAfterMs on durable bots).
Parameters
options?
wait?
boolean
Returns
Promise<string[]>
dispose()
dispose():
void
Defined in: packages/orchestration/src/orchestrator.ts:548
Not restartable: clears every event subscription.
Returns
void
expireQuestions()
expireQuestions(
now?):Promise<HumanQuestion[]>
Defined in: packages/orchestration/src/orchestrator.ts:207
Parameters
now?
number
Returns
Promise<HumanQuestion[]>
explain()
explain(
ticketId):Promise<SkipReason>
Defined in: packages/orchestration/src/orchestrator.ts:531
Why a ticket isn't dispatching.
Parameters
ticketId
string
Returns
Promise<SkipReason>
getTicket()
getTicket(
id):Promise<Ticket|null>
Defined in: packages/orchestration/src/orchestrator.ts:283
Parameters
id
string
Returns
Promise<Ticket | null>
listQuestions()
listQuestions(
filter?):Promise<HumanQuestion[]>
Defined in: packages/orchestration/src/orchestrator.ts:205
Parameters
filter?
Returns
Promise<HumanQuestion[]>
listRuns()
listRuns(
filter?):Promise<Run[]>
Defined in: packages/orchestration/src/orchestrator.ts:318
Parameters
filter?
agentName?
string
status?
("pending" | "running" | "failed" | "cancelled" | "paused" | "completed")[]
ticketId?
string
Returns
Promise<Run[]>
listTickets()
listTickets(
filter?):Promise<Ticket[]>
Defined in: packages/orchestration/src/orchestrator.ts:287
Parameters
filter?
assignee?
string
status?
("needs_input" | "backlog" | "queued" | "in_progress" | "review" | "done" | "failed" | "cancelled")[]
tags?
string[]
Returns
Promise<Ticket[]>
loadRunEvents()
loadRunEvents(
runId):Promise<BaleybotStreamEvent[]>
Defined in: packages/orchestration/src/orchestrator.ts:323
A run's stream events, for replay.
Parameters
runId
string
Returns
Promise<BaleybotStreamEvent[]>
reconcile()
reconcile(
options?):Promise<ReconcileReport>
Defined in: packages/orchestration/src/orchestrator.ts:452
The cron heartbeat for serverless orchestration. Every instance may die mid-run, so the store is reconciled with reality:
- a
runningrun whose heartbeat is older thanstaleAfterMsis failed, and its ticket queued again (a durable agent then continues from its last checkpoint) — or failed, aftermaxRecoveries; - a run whose ticket ended, or moved to another run, is cancelled;
- an
in_progressticket whose run is no longer active is set to match; - questions past their deadline expire;
- then one dispatch pass.
Runs this instance is executing are never touched. Safe to run on many instances at once: every ticket change is a claim on the state it read.
Parameters
options?
ReconcileOptions = {}
Returns
Promise<ReconcileReport>
registerAgent()
registerAgent(
registration):RegisteredAgent
Defined in: packages/orchestration/src/orchestrator.ts:312
Parameters
registration
Returns
resumeQuestion()
resumeQuestion(
questionId):Promise<Run>
Defined in: packages/orchestration/src/orchestrator.ts:249
Retry execution after an accepted answer if the original dispatch could not start.
Parameters
questionId
string
Returns
Promise<Run>
start()
start():
void
Defined in: packages/orchestration/src/orchestrator.ts:535
Returns
void
stop()
stop():
Promise<void>
Defined in: packages/orchestration/src/orchestrator.ts:540
Stop the scheduler and cancel this instance's runs. Restartable with start().
Returns
Promise<void>
updateTicket()
updateTicket(
id,changes):Promise<Ticket>
Defined in: packages/orchestration/src/orchestrator.ts:297
Change a ticket, fenced like a run's settle: the write is a claim on the
ticket as read, made only while the same run (or none) holds it. A ticket
a run is working on keeps its status, because the run settles it from the
status it claimed; cancel the run (cancelTicket) to stop it instead.
Parameters
id
string
changes
Partial<Ticket>
Returns
Promise<Ticket>
waitForTicket()
waitForTicket(
ticketId,options?):Promise<Ticket>
Defined in: packages/orchestration/src/orchestrator.ts:381
Wait for a ticket to end (done, failed, cancelled) or, unless
waitThroughNeedsInput, to need input. Resolves at once if it already has.
Parameters
ticketId
string
options?
pollMs?
number
timeoutMs?
number
waitThroughNeedsInput?
boolean
Returns
Promise<Ticket>
Example
orch.start();
const ticket = await orch.waitForTicket(myTicket.id, { timeoutMs: 120_000 });
console.log(ticket.status); // 'done', 'failed', or 'cancelled'
withdrawQuestion()
withdrawQuestion(
questionId):Promise<HumanQuestion>
Defined in: packages/orchestration/src/orchestrator.ts:206
Parameters
questionId
string
Returns
Promise<HumanQuestion>