The orchestrator factory creates and wires together all components of the Longshot system, including the planner, worker pool, merge queue, reconciler, and monitor.
createOrchestrator()
Creates a fully wired orchestrator instance ready to execute a build request.
async function createOrchestrator(
request: string,
callbacks?: OrchestratorCallbacks
): Promise<Orchestrator>
The natural-language build request to execute
Optional callbacks for lifecycle events and monitoring
OrchestratorCallbacks
Callbacks for all major orchestrator events:
interface OrchestratorCallbacks {
onTaskCreated?: (task: Task) => void;
onTaskCompleted?: (task: Task, handoff: Handoff) => void;
onIterationComplete?: (iteration: number, tasks: Task[], handoffs: Handoff[]) => void;
onError?: (error: Error) => void;
onSweepComplete?: (result: SweepResult) => void;
onReconcilerError?: (error: Error) => void;
onWorkerTimeout?: (workerId: string, taskId: string) => void;
onEmptyDiff?: (workerId: string, taskId: string) => void;
onMetricsUpdate?: (snapshot: MetricsSnapshot) => void;
onTaskStatusChange?: (task: Task, oldStatus: string, newStatus: string) => void;
onFinalizationStart?: () => void;
onFinalizationAttempt?: (attempt: number, sweepResult: SweepResult) => void;
onFinalizationComplete?: (attempts: number, passed: boolean) => void;
}
Orchestrator Interface
The created orchestrator exposes:
interface Orchestrator {
planner: Planner;
subplanner: Subplanner;
reconciler: Reconciler;
workerPool: WorkerPool;
mergeQueue: MergeQueue;
taskQueue: TaskQueue;
monitor: Monitor;
start(): Promise<void>;
stop(): Promise<void>;
waitForCompletion(): Promise<void>;
}
Methods
start()
Starts the orchestrator execution loop.
await orchestrator.start();
stop()
Gracefully stops the orchestrator and all components.
await orchestrator.stop();
waitForCompletion()
Waits until all tasks are complete and the merge queue is drained.
await orchestrator.waitForCompletion();
Component Wiring
The factory automatically wires:
- Configuration — Loads from environment and validates
- Tracer — Sets up distributed tracing
- Git mutex — Serializes git operations
- Task queue — Priority-based task queue with lifecycle tracking
- Worker pool — Ephemeral sandbox manager
- Merge queue — Serial merge pipeline with conflict handling
- Monitor — Metrics collection and health checks
- Reconciler — Periodic build/test sweeps
- Subplanner — Recursive task decomposition
- Root planner — Top-level planning loop
Finalization Phase
After all tasks complete, the orchestrator runs a finalization phase:
- Drain merge queue — Wait for all pending merges
- Retry unmerged branches — Attempt to merge any blocked branches
- Final sweep — Run reconciler one last time
- Report — Emit finalization metrics
The finalization phase runs up to FINALIZATION_MAX_ATTEMPTS times (default: 3) until the build passes or attempts are exhausted.
Usage Example
import { createOrchestrator } from "@longshot/orchestrator";
const orchestrator = await createOrchestrator(
"Build a REST API according to SPEC.md",
{
onTaskCreated: (task) => {
console.log(`Created task: ${task.description}`);
},
onTaskCompleted: (task, handoff) => {
console.log(`Completed: ${task.description}`);
console.log(`Files changed: ${handoff.filesChanged.length}`);
},
onMetricsUpdate: (metrics) => {
console.log(`Active: ${metrics.activeWorkers}, Pending: ${metrics.pendingTasks}`);
},
onFinalizationComplete: (attempts, passed) => {
console.log(`Finalization ${passed ? 'passed' : 'failed'} after ${attempts} attempts`);
},
}
);
await orchestrator.start();
await orchestrator.waitForCompletion();
await orchestrator.stop();
console.log("Build complete!");
Environment Configuration
The orchestrator reads configuration from environment variables:
LLM_BASE_URL, LLM_API_KEY — LLM providerGIT_REPO_URL, GIT_TOKEN — Target repositoryMAX_WORKERS — Concurrency limitWORKER_TIMEOUT — Worker timeout in secondsMERGE_STRATEGY — fast-forward, rebase, or merge-commitFINALIZATION_ENABLED — Enable/disable finalization phaseFINALIZATION_MAX_ATTEMPTS — Max finalization retries
See Configuration for all options.