Skip to main content

​
Overview

The main module serves as the CLI entry point for the Longshot orchestrator. It loads environment variables, initializes logging and tracing, creates the orchestrator instance, and manages the full execution lifecycle. Location: packages/orchestrator/src/main.ts

​
Key Functions

​
main()

The primary entry point that orchestrates the entire execution flow. 
async function main(): Promise<void>
Behavior:
  1. Loads environment variables from .env file
  2. Configures log level from LOG_LEVEL env var
  3. Enables file logging and tracing
  4. Creates orchestrator instance with comprehensive callbacks
  5. Runs the orchestrator with the user’s request
  6. Handles graceful shutdown on SIGINT/SIGTERM
  7. Exits with code 1 if finalization fails
Environment Variables:
  • LOG_LEVEL - Sets logging verbosity (debug, info, warn, error)
  • LONGSHOT_PROMPTS_ROOT - Override directory for prompt files

​
formatDuration()

Utility function for human-readable duration formatting. 
function formatDuration(ms: number): string
​
ms
number
required
Duration in milliseconds
Returns: Formatted string like 5m 30s or 1500ms

​
Orchestrator Callbacks

The main module registers extensive callbacks to monitor orchestrator progress:

​
Task Lifecycle

onTaskCreated - Logs when new tasks are created 
onTaskCreated(task: Task): void
Logs: taskId, parentId, description (first 200 chars) onTaskCompleted - Logs task completion with metrics 
onTaskCompleted(task: Task, handoff: Handoff): void
Logs: Status, duration, files changed, lines added/removed, tokens used, tool calls Anomaly Detection: Warns if a task changes >100 files or adds >50,000 lines

​
Iteration Progress

onIterationComplete - Called after each planning iteration 
onIterationComplete(iteration: number, tasks: Task[], handoffs: Handoff[]): void
Logs: Iteration number, task/handoff counts, orchestrator snapshot

​
Reconciler Events

onSweepComplete - Called after each reconciler sweep 
onSweepComplete(result: SweepResult): void
Logs: Fix tasks created, build/test health, conflict markers

​
Finalization Phase

onFinalizationStart - Marks start of finalization 
onFinalizationStart(): void
onFinalizationAttempt - Called for each finalization attempt 
onFinalizationAttempt(attempt: number, sweepResult: SweepResult): void
onFinalizationComplete - Final finalization status 
onFinalizationComplete(attempts: number, passed: boolean): void

​
Metrics Updates

onMetricsUpdate - Periodic metrics snapshot including merge queue stats 
onMetricsUpdate(snapshot: MetricsSnapshot): void

​
Usage Example

# Run with environment variables configured
LOG_LEVEL=debug \
LLM_BASE_URL=http://localhost:8000 \
GIT_REPO_URL=https://github.com/user/repo.git \
node packages/orchestrator/dist/main.js "Build the feature from SPEC.md"

​
Output Files

The main module creates three log files in the current working directory:
  • longshot-{timestamp}.log - Debug-level file logs
  • trace-{timestamp}.jsonl - NDJSON trace spans for observability
  • llm-detail-{timestamp}.jsonl - LLM request/response details

​
Exit Codes

​
0
success
Run completed successfully with all checks passing
​
1
failure
Run failed finalization (build failed, tests failed, or branches unmerged)

​
Request Input

The orchestrator accepts a request as the first command-line argument: 
const request = process.argv[2] || 
  "Build Minecraft according to SPEC.md and FEATURES.json in the target repository."
If no argument is provided, it uses the default Minecraft request as shown above.

​
Shutdown Handling

process.on('SIGINT', shutdown)
process.on('SIGTERM', shutdown)
Graceful shutdown:
  1. Stops the orchestrator (planner, workers, reconciler)
  2. Writes final summary logs
  3. Closes file logging and tracing handles
  4. Exits with appropriate code

Build docs developers (and LLMs) love

Get started for freeTalk to us