Skip to main content

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​

OrchestratorConfig

Returns​

Orchestrator

Properties​

agents​

readonly agents: AgentRegistry

Defined in: packages/orchestration/src/orchestrator.ts:150


costs​

readonly costs: CostTracker

Defined in: packages/orchestration/src/orchestrator.ts:151


events​

readonly events: EventBus<OrchestrationEventMap>

Defined in: packages/orchestration/src/orchestrator.ts:149


runs​

readonly runs: RunManager

Defined in: packages/orchestration/src/orchestrator.ts:152


scheduler​

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

QuestionAnswer

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​

TicketConfig

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​

TicketConfig[]

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

QuestionFilter

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 running run whose heartbeat is older than staleAfterMs is failed, and its ticket queued again (a durable agent then continues from its last checkpoint) — or failed, after maxRecoveries;
  • a run whose ticket ended, or moved to another run, is cancelled;
  • an in_progress ticket 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​

AgentRegistration

Returns​

RegisteredAgent


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>