Class: Orchestrator
Defined in: packages/orchestration/src/orchestrator.ts:96
Top-level orchestration facade.
Wires together the ticket store, run manager, agent registry, scheduler, and event bus into a single entry point.
Example
// With Supabase
const orch = new Orchestrator({ supabase, userId: 'user-123' });
// 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:109
Parameters
config
Returns
Orchestrator
Properties
agents
readonlyagents:AgentRegistry
Defined in: packages/orchestration/src/orchestrator.ts:98
costs
readonlycosts:CostTracker
Defined in: packages/orchestration/src/orchestrator.ts:99
events
readonlyevents:EventBus<OrchestrationEventMap>
Defined in: packages/orchestration/src/orchestrator.ts:97
runs
readonlyruns:RunManager
Defined in: packages/orchestration/src/orchestrator.ts:100
scheduler
readonlyscheduler:Scheduler
Defined in: packages/orchestration/src/orchestrator.ts:101
Methods
cancelRun()
cancelRun(
runId):Promise<void>
Defined in: packages/orchestration/src/orchestrator.ts:205
Cancel a run
Parameters
runId
string
Returns
Promise<void>
cancelTicket()
cancelTicket(
ticketId,options?):Promise<Ticket>
Defined in: packages/orchestration/src/orchestrator.ts:224
Cancel a ticket regardless of state — kills any active run and marks the ticket cancelled. Idempotent: returns the ticket as-is if it's already in a terminal state (done / failed / cancelled).
- Active run: aborts it. The run-manager's abort path already updates both the run and the ticket to 'cancelled' and emits the events, so we don't double-update here.
- No active run (queued / backlog / paused / etc): just updates the ticket status and emits ticket.updated.
Provided so the coordinator (and external MCP clients) have a single tool that DTRT for any ticket state instead of needing to chain list_runs → cancel_run → update_ticket.
Parameters
ticketId
string
options?
reason?
string
Returns
Promise<Ticket>
createTicket()
createTicket(
rawConfig):Promise<Ticket>
Defined in: packages/orchestration/src/orchestrator.ts:133
Create a ticket (merges ticketDefaults from constructor config)
Parameters
rawConfig
Returns
Promise<Ticket>
createTickets()
createTickets(
configs):Promise<Ticket[]>
Defined in: packages/orchestration/src/orchestrator.ts:250
Create multiple tickets in sequence (order matters for dependsOn references)
Parameters
configs
Returns
Promise<Ticket[]>
deleteTicket()
deleteTicket(
id):Promise<void>
Defined in: packages/orchestration/src/orchestrator.ts:183
Delete a ticket
Parameters
id
string
Returns
Promise<void>
dispatch()
dispatch(
ticketId,agentName):Promise<Run>
Defined in: packages/orchestration/src/orchestrator.ts:262
Dispatch a ticket to a specific agent immediately, bypassing the scheduler. Returns the completed Run.
Parameters
ticketId
string
agentName
string
Returns
Promise<Run>
dispose()
dispose():
void
Defined in: packages/orchestration/src/orchestrator.ts:329
Permanently tear down the orchestrator (not restartable)
Returns
void
explain()
explain(
ticketId):Promise<SkipReason>
Defined in: packages/orchestration/src/orchestrator.ts:304
Diagnose why a ticket isn't dispatching. Delegates to scheduler.explain() for structured diagnostics.
Parameters
ticketId
string
Returns
Promise<SkipReason>
getTicket()
getTicket(
id):Promise<Ticket|null>
Defined in: packages/orchestration/src/orchestrator.ts:166
Get a ticket by ID
Parameters
id
string
Returns
Promise<Ticket | null>
listRuns()
listRuns(
filter?):Promise<Run[]>
Defined in: packages/orchestration/src/orchestrator.ts:195
List runs with optional filters
Parameters
filter?
agentName?
string
status?
ticketId?
string
Returns
Promise<Run[]>
listTickets()
listTickets(
filter?):Promise<Ticket[]>
Defined in: packages/orchestration/src/orchestrator.ts:171
List tickets with optional filters
Parameters
filter?
assignee?
string
status?
tags?
string[]
Returns
Promise<Ticket[]>
loadRunEvents()
loadRunEvents(
runId):Promise<BaleybotStreamEvent[]>
Defined in: packages/orchestration/src/orchestrator.ts:200
Load events for a run (for replay)
Parameters
runId
string
Returns
Promise<BaleybotStreamEvent[]>
registerAgent()
registerAgent(
registration):RegisteredAgent
Defined in: packages/orchestration/src/orchestrator.ts:188
Register an agent
Parameters
registration
Returns
start()
start():
void
Defined in: packages/orchestration/src/orchestrator.ts:309
Start the scheduler heartbeat
Returns
void
stop()
stop():
Promise<void>
Defined in: packages/orchestration/src/orchestrator.ts:314
Stop everything gracefully (restartable — call start() to resume)
Returns
Promise<void>
updateTicket()
updateTicket(
id,changes):Promise<Ticket>
Defined in: packages/orchestration/src/orchestrator.ts:176
Update a ticket
Parameters
id
string
changes
Partial<Ticket>
Returns
Promise<Ticket>
waitForTicket()
waitForTicket(
ticketId,options?):Promise<Ticket>
Defined in: packages/orchestration/src/orchestrator.ts:279
Wait for a ticket to reach a terminal state (done, failed, cancelled). Resolves immediately if the ticket is already terminal.
Parameters
ticketId
string
options?
timeoutMs?
number
Returns
Promise<Ticket>
Example
orch.start();
const ticket = await orch.waitForTicket(myTicket.id, { timeoutMs: 120_000 });
console.log(ticket.status); // 'done', 'failed', or 'cancelled'