@harness-engineering/orchestrator 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,443 @@
+import { Issue, AgentEvent, TokenUsage, WorkflowConfig, Result, WorkflowDefinition, IssueTrackerClient, TrackerConfig, WorkspaceConfig, HooksConfig, AgentBackend, SessionStartParams, AgentSession, AgentError, TurnParams, TurnResult } from '@harness-engineering/types';
+import { EventEmitter } from 'node:events';
+
+/**
+ * Run attempt lifecycle phases (internal to orchestrator).
+ * Tracks the current phase of a single run attempt.
+ */
+type RunAttemptPhase = 'PreparingWorkspace' | 'BuildingPrompt' | 'LaunchingAgent' | 'InitializingSession' | 'StreamingTurn' | 'Finishing' | 'Succeeded' | 'Failed' | 'TimedOut' | 'Stalled' | 'CanceledByReconciliation';
+/**
+ * Live session metadata tracked while an agent subprocess is running.
+ */
+interface LiveSession {
+    sessionId: string;
+    backendName: string;
+    agentPid: number | null;
+    startedAt: string;
+    lastEvent: string | null;
+    lastTimestamp: string | null;
+    lastMessage: string | null;
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+    lastReportedInputTokens: number;
+    lastReportedOutputTokens: number;
+    lastReportedTotalTokens: number;
+    turnCount: number;
+}
+/**
+ * Entry in the running map: one active worker.
+ */
+interface RunningEntry {
+    issueId: string;
+    identifier: string;
+    issue: Issue;
+    attempt: number | null;
+    workspacePath: string;
+    startedAt: string;
+    phase: RunAttemptPhase;
+    session: LiveSession | null;
+}
+/**
+ * Entry in the retry queue.
+ */
+interface RetryEntry {
+    issueId: string;
+    identifier: string;
+    attempt: number;
+    dueAtMs: number;
+    error: string | null;
+}
+/**
+ * Token totals for observability.
+ */
+interface TokenTotals {
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+    secondsRunning: number;
+}
+/**
+ * Rate limit snapshot (populated by agent events).
+ */
+interface RateLimitSnapshot {
+    requestsRemaining: number | null;
+    requestsLimit: number | null;
+    tokensRemaining: number | null;
+    tokensLimit: number | null;
+}
+/**
+ * Single authoritative in-memory orchestrator state.
+ */
+interface OrchestratorState {
+    pollIntervalMs: number;
+    maxConcurrentAgents: number;
+    running: Map<string, RunningEntry>;
+    claimed: Set<string>;
+    retryAttempts: Map<string, RetryEntry>;
+    completed: Set<string>;
+    tokenTotals: TokenTotals;
+    rateLimits: RateLimitSnapshot;
+}
+
+/**
+ * Discriminated union of events that drive the orchestrator state machine.
+ * All events are data -- the caller constructs them from I/O results.
+ */
+type OrchestratorEvent = TickEvent | WorkerExitEvent | AgentUpdateEvent | RetryFiredEvent | StallDetectedEvent;
+interface TickEvent {
+    type: 'tick';
+    candidates: Issue[];
+    runningStates: Map<string, Issue>;
+    /** Caller-supplied wall clock (ms since epoch). Keeps state machine pure. */
+    nowMs: number;
+}
+interface WorkerExitEvent {
+    type: 'worker_exit';
+    issueId: string;
+    reason: 'normal' | 'error';
+    error?: string | undefined;
+    attempt: number | null;
+}
+interface AgentUpdateEvent {
+    type: 'agent_update';
+    issueId: string;
+    event: AgentEvent;
+}
+interface RetryFiredEvent {
+    type: 'retry_fired';
+    issueId: string;
+    candidates: Issue[];
+    /** Caller-supplied wall clock (ms since epoch). Keeps state machine pure. */
+    nowMs: number;
+}
+interface StallDetectedEvent {
+    type: 'stall_detected';
+    issueId: string;
+}
+/**
+ * Discriminated union of side effects returned by the state machine.
+ * These are data describing what to do -- the orchestrator loop executes them.
+ */
+type SideEffect = DispatchEffect | StopEffect | ScheduleRetryEffect | ReleaseClaimEffect | CleanWorkspaceEffect | UpdateTokensEffect | EmitLogEffect;
+interface DispatchEffect {
+    type: 'dispatch';
+    issue: Issue;
+    attempt: number | null;
+}
+interface StopEffect {
+    type: 'stop';
+    issueId: string;
+    reason: string;
+}
+interface ScheduleRetryEffect {
+    type: 'scheduleRetry';
+    issueId: string;
+    identifier: string;
+    attempt: number;
+    delayMs: number;
+    error: string | null;
+}
+interface ReleaseClaimEffect {
+    type: 'releaseClaim';
+    issueId: string;
+}
+interface CleanWorkspaceEffect {
+    type: 'cleanWorkspace';
+    issueId: string;
+    identifier: string;
+}
+interface UpdateTokensEffect {
+    type: 'updateTokens';
+    issueId: string;
+    usage: TokenUsage;
+}
+interface EmitLogEffect {
+    type: 'emitLog';
+    level: 'info' | 'warn' | 'error';
+    message: string;
+    context?: Record<string, unknown>;
+}
+
+/**
+ * Calculate retry delay based on attempt number and retry type.
+ *
+ * Continuation retries: fixed 1000ms delay.
+ * Failure retries: exponential backoff 10000 * 2^(attempt-1), capped at maxRetryBackoffMs.
+ */
+declare function calculateRetryDelay(attempt: number, type: 'continuation' | 'failure', maxRetryBackoffMs?: number): number;
+
+/**
+ * Sort candidates by dispatch priority (stable sort).
+ * 1. priority ascending (1..4 preferred; null sorts last)
+ * 2. createdAt oldest first (null sorts last)
+ * 3. identifier lexicographic tie-breaker
+ */
+declare function sortCandidates(issues: readonly Issue[]): Issue[];
+/**
+ * Check if a single issue is dispatch-eligible.
+ * State comparisons are case-insensitive.
+ */
+declare function isEligible(issue: Issue, state: OrchestratorState, activeStates: string[], terminalStates: string[]): boolean;
+/**
+ * Select and sort eligible candidates from a list of issues.
+ */
+declare function selectCandidates(issues: readonly Issue[], state: OrchestratorState, activeStates: string[], terminalStates: string[]): Issue[];
+
+/**
+ * Get the number of available global concurrency slots.
+ */
+declare function getAvailableSlots(state: OrchestratorState): number;
+/**
+ * Count running entries by normalized (lowercase) issue state.
+ */
+declare function getPerStateCount(running: ReadonlyMap<string, RunningEntry>): Map<string, number>;
+/**
+ * Check if dispatching an issue in the given state is allowed
+ * by both global and per-state concurrency limits.
+ */
+declare function canDispatch(state: OrchestratorState, issueState: string, maxConcurrentAgentsByState: Record<string, number>): boolean;
+
+/**
+ * Reconcile running issues against their current tracker states.
+ *
+ * For each running issue found in runningStates:
+ * - Terminal state -> stop + cleanWorkspace + releaseClaim
+ * - Neither active nor terminal -> stop + releaseClaim (no workspace cleanup)
+ * - Still active -> no effects (keep running)
+ *
+ * Issues not found in runningStates are left running (state refresh may have
+ * partially failed; retry next tick per spec).
+ */
+declare function reconcile(state: OrchestratorState, runningStates: ReadonlyMap<string, Issue>, activeStates: string[], terminalStates: string[]): SideEffect[];
+
+interface ApplyEventResult {
+    nextState: OrchestratorState;
+    effects: SideEffect[];
+}
+/**
+ * Pure state machine transition function.
+ *
+ * Takes the current state, an event, and config.
+ * Returns the next state and a list of side effects to execute.
+ * No I/O is performed -- all side effects are returned as data.
+ */
+declare function applyEvent(state: OrchestratorState, event: OrchestratorEvent, config: WorkflowConfig): ApplyEventResult;
+
+/**
+ * Create an empty OrchestratorState initialized from config.
+ */
+declare function createEmptyState(config: WorkflowConfig): OrchestratorState;
+
+declare class WorkflowLoader {
+    loadWorkflow(filePath: string): Promise<Result<WorkflowDefinition, Error>>;
+}
+
+declare function validateWorkflowConfig(config: unknown): Result<WorkflowConfig, Error>;
+declare function getDefaultConfig(): WorkflowConfig;
+
+/**
+ * Adapter for using a markdown roadmap file as an issue tracker.
+ *
+ * This adapter parses a standard Harness roadmap file, extracts features,
+ * and maps them to the internal Issue model using deterministic hashing
+ * for identifiers.
+ */
+declare class RoadmapTrackerAdapter implements IssueTrackerClient {
+    private config;
+    /**
+     * Creates a new RoadmapTrackerAdapter.
+     *
+     * @param config - The tracker configuration including the file path
+     */
+    constructor(config: TrackerConfig);
+    /**
+     * Fetches all issues that are in an "active" state according to the config.
+     */
+    fetchCandidateIssues(): Promise<Result<Issue[], Error>>;
+    /**
+     * Fetches issues that match any of the given state names.
+     *
+     * @param stateNames - List of statuses to filter by
+     */
+    fetchIssuesByStates(stateNames: string[]): Promise<Result<Issue[], Error>>;
+    /**
+     * Fetches full issue details for a list of identifiers.
+     *
+     * @param issueIds - List of issue IDs to fetch
+     */
+    fetchIssueStatesByIds(issueIds: string[]): Promise<Result<Map<string, Issue>, Error>>;
+    /**
+     * Maps a raw RoadmapFeature from the parser to the unified Issue model.
+     */
+    private mapFeatureToIssue;
+    /**
+     * Generates a deterministic, URL-safe identifier for a feature name.
+     */
+    private generateId;
+}
+
+/**
+ * Interface for Linear GraphQL tool extension.
+ * This is a stub implementation for Phase 4.
+ */
+interface LinearGraphQLExtension {
+    query(query: string, variables?: Record<string, unknown>): Promise<Result<unknown, Error>>;
+}
+declare class LinearGraphQLStub implements LinearGraphQLExtension {
+    query(query: string, _variables?: Record<string, unknown>): Promise<Result<unknown, Error>>;
+}
+
+declare class WorkspaceManager {
+    private config;
+    constructor(config: WorkspaceConfig);
+    /**
+     * Sanitizes an issue identifier to be safe for use as a directory name.
+     */
+    sanitizeIdentifier(identifier: string): string;
+    /**
+     * Resolves the full path for an issue's workspace.
+     */
+    resolvePath(identifier: string): string;
+    /**
+     * Ensures the workspace directory exists.
+     */
+    ensureWorkspace(identifier: string): Promise<Result<string, Error>>;
+    /**
+     * Checks if a workspace exists.
+     */
+    exists(identifier: string): Promise<boolean>;
+    /**
+     * Removes a workspace directory.
+     */
+    removeWorkspace(identifier: string): Promise<Result<void, Error>>;
+}
+
+declare class WorkspaceHooks {
+    private config;
+    constructor(config: HooksConfig);
+    /**
+     * Executes a shell hook in the specified workspace directory.
+     */
+    executeHook(hookName: keyof Omit<HooksConfig, 'timeoutMs'>, cwd: string): Promise<Result<void, Error>>;
+    afterCreate(cwd: string): Promise<Result<void, Error>>;
+    beforeRun(cwd: string): Promise<Result<void, Error>>;
+    afterRun(cwd: string): Promise<Result<void, Error>>;
+    beforeRemove(cwd: string): Promise<Result<void, Error>>;
+}
+
+declare class MockBackend implements AgentBackend {
+    readonly name = "mock";
+    startSession(params: SessionStartParams): Promise<Result<AgentSession, AgentError>>;
+    runTurn(session: AgentSession, _params: TurnParams): AsyncGenerator<AgentEvent, TurnResult, void>;
+    stopSession(_session: AgentSession): Promise<Result<void, AgentError>>;
+    healthCheck(): Promise<Result<void, AgentError>>;
+}
+
+declare class ClaudeBackend implements AgentBackend {
+    readonly name = "claude";
+    private command;
+    constructor(command?: string);
+    startSession(params: SessionStartParams): Promise<Result<AgentSession, AgentError>>;
+    runTurn(session: AgentSession, params: TurnParams): AsyncGenerator<AgentEvent, TurnResult, void>;
+    stopSession(_session: AgentSession): Promise<Result<void, AgentError>>;
+    healthCheck(): Promise<Result<void, AgentError>>;
+}
+
+declare class PromptRenderer {
+    private engine;
+    constructor();
+    render(template: string, context: Record<string, unknown>): Promise<string>;
+}
+
+/**
+ * The central orchestrator that manages the lifecycle of coding agents.
+ *
+ * It polls an issue tracker for candidate tasks, manages ephemeral workspaces,
+ * runs agents to resolve issues, and updates the tracker with progress.
+ *
+ * @fires Orchestrator#state_change Emitted when the internal state machine transitions
+ * @fires Orchestrator#agent_event Emitted when an agent produces an output or thought
+ */
+declare class Orchestrator extends EventEmitter {
+    private state;
+    private config;
+    private tracker;
+    private workspace;
+    private hooks;
+    private runner;
+    private renderer;
+    private promptTemplate;
+    private server?;
+    private interval?;
+    private logger;
+    /**
+     * Creates a new Orchestrator instance.
+     *
+     * @param config - The workflow configuration
+     * @param promptTemplate - The template used to generate agent instructions
+     * @param overrides - Optional dependency overrides for testing or custom behavior
+     */
+    constructor(config: WorkflowConfig, promptTemplate: string, overrides?: {
+        tracker?: IssueTrackerClient;
+        backend?: AgentBackend;
+    });
+    private createTracker;
+    private createBackend;
+    /**
+     * Run a single tick of the orchestrator loop.
+     *
+     * This method fetches the latest issue states, applies them to the state machine,
+     * and executes any resulting side effects (dispatching new agents, stopping agents, etc.).
+     */
+    tick(): Promise<void>;
+    /**
+     * Processes a side effect generated by the state machine.
+     *
+     * @param effect - The effect to handle
+     */
+    private handleEffect;
+    /**
+     * Dispatches a new agent to work on an issue.
+     *
+     * @param issue - The issue to resolve
+     * @param attempt - The retry attempt number
+     */
+    private dispatchIssue;
+    /**
+     * Runs an agent session in a background task to avoid blocking the main loop.
+     */
+    private runAgentInBackgroundTask;
+    /**
+     * Informs the state machine that an agent worker has exited.
+     */
+    private emitWorkerExit;
+    /**
+     * Stops execution for a specific issue.
+     *
+     * @param issueId - The ID of the issue to stop
+     */
+    private stopIssue;
+    /**
+     * Starts the polling loop and the internal HTTP server.
+     */
+    start(): void;
+    /**
+     * Stops the orchestrator, clearing the polling interval and stopping the server.
+     */
+    stop(): Promise<void>;
+    /**
+     * Returns a point-in-time snapshot of the orchestrator's internal state.
+     */
+    getSnapshot(): Record<string, unknown>;
+}
+
+/**
+ * Launches the Ink TUI for the given Orchestrator instance.
+ * Returns a function to wait for the TUI to exit.
+ */
+declare function launchTUI(orchestrator: Orchestrator): {
+    waitUntilExit: () => Promise<void>;
+};
+
+export { type AgentUpdateEvent, type ApplyEventResult, ClaudeBackend, type CleanWorkspaceEffect, type DispatchEffect, type EmitLogEffect, type LinearGraphQLExtension, LinearGraphQLStub, type LiveSession, MockBackend, Orchestrator, type OrchestratorEvent, type OrchestratorState, PromptRenderer, type RateLimitSnapshot, type ReleaseClaimEffect, type RetryEntry, type RetryFiredEvent, RoadmapTrackerAdapter, type RunAttemptPhase, type RunningEntry, type ScheduleRetryEffect, type SideEffect, type StallDetectedEvent, type StopEffect, type TickEvent, type TokenTotals, type UpdateTokensEffect, type WorkerExitEvent, WorkflowLoader, WorkspaceHooks, WorkspaceManager, applyEvent, calculateRetryDelay, canDispatch, createEmptyState, getAvailableSlots, getDefaultConfig, getPerStateCount, isEligible, launchTUI, reconcile, selectCandidates, sortCandidates, validateWorkflowConfig };