@orc-brain/core 1.0.0

package/dist/orchestrator.d.ts

@@ -0,0 +1,242 @@
+/**
+ * Orchestrator core (§3, §5). Owns the Goal, the Scope DAG, and the Run state
+ * machine. Runs the dispatch loop: on each tick, take ready tasks (dependencies
+ * met, scope approved, budget available, concurrency slot free), consult the
+ * Model Router, and hand a fully-specified WorkerSpec to the Worker Manager.
+ *
+ * Phase 2 (§15): Planner-driven DAG materialization + plan approval,
+ * pause/resume with session persistence, and bounded retries land here on top
+ * of the Phase 1 safety-wired dispatch loop.
+ */
+import type { ExternalRef, Goal, OrchestratorConfig, Plan, Project, Run, Scope, Task } from "@orc-brain/shared";
+import type { Store } from "./store/index.js";
+import type { AuditSink, SafetyLayer } from "./safety/index.js";
+import type { EventBus } from "./eventBus.js";
+import type { BudgetTracker } from "./budgetTracker.js";
+import type { WorkerManager } from "./workerManager.js";
+import type { Planner } from "./planner.js";
+import type { EscalationManager } from "./escalation.js";
+import type { ReportingEngine } from "./reporting.js";
+import type { Backpressure } from "./backpressure.js";
+import type { WorktreeManager } from "./worktrees.js";
+/**
+ * Hook the autonomous controller registers so the orchestrator can hand off a
+ * quiesced run (all tasks terminal) instead of finalizing it itself
+ * (autonomous-loop.md §3.1, G4). Fire-and-forget: the controller owns the
+ * done / re-plan / pause decision.
+ */
+export interface AutoLoopHook {
+    onRunQuiesced(runId: string): void;
+}
+/** Wires the core collaborators together. */
+export interface OrchestratorDeps {
+    store: Store;
+    bus: EventBus;
+    config: OrchestratorConfig;
+    safety: SafetyLayer;
+    workers: WorkerManager;
+    budget: BudgetTracker;
+    audit: AuditSink;
+    planner: Planner;
+    escalation: EscalationManager;
+    reporting: ReportingEngine;
+    backpressure: Backpressure;
+    worktrees: WorktreeManager;
+}
+/** The orchestration core. In-proc methods are invoked by the API layer. */
+export declare class Orchestrator {
+    private readonly deps;
+    private readonly running;
+    /** Run each in-flight task belongs to: per-run counts + pause/panic scoping. */
+    private readonly runOfTask;
+    /** Tasks blocked by an escalation, so a settling worker isn't retried (§8.5). */
+    private readonly blocked;
+    /** Set on shutdown so late worker callbacks don't touch a closed store. */
+    private stopped;
+    /** Autonomous controller, registered when auto-loop is enabled (§3.1). */
+    private autoLoop?;
+    /** Tasks-per-hour throttle, shared across runs (spec 002 §R14). */
+    private readonly pacer;
+    /** Last engaged pacing gate, so `pacing.hold` is edge-triggered (§R16). */
+    private pacingHold;
+    constructor(deps: OrchestratorDeps);
+    /** Number of in-flight workers belonging to one run. */
+    private runningCountFor;
+    /** In-flight handles belonging to one run (pause/panic never cross runs). */
+    private handlesFor;
+    /** Publishes `pacing.hold` once per engagement (spec 002 §R16). */
+    private emitPacingHold;
+    /** Interrupts the worker of a task the escalation manager just blocked (§8.5). */
+    private blockTask;
+    /**
+     * Applies an operator resolution to a blocked escalation (§8.5): deny-&-instruct
+     * and approve-once re-queue the task (with guidance / a single-use exemption),
+     * skip marks it skipped. Then the dispatch loop is re-kicked.
+     */
+    resolveEscalation(escalationId: string, action: "deny_instruct" | "approve_once" | "skip_task", message?: string): void;
+    createGoal(input: Parameters<Store["createGoal"]>[0]): Goal;
+    /**
+     * Feature flow (spec 002 §R4, spec 003 §R4): creates a goal under a project
+     * and immediately kicks planning, fire-and-forget. The single entrypoint for
+     * `POST /api/projects/:id/goals` and plugin task imports, so the two paths
+     * cannot drift. A planner failure drops the goal back to draft.
+     */
+    createFeatureGoal(project: Project, input: {
+        objective: string;
+        title?: string;
+        external_ref?: ExternalRef | null;
+    }): Goal;
+    createScope(input: Parameters<Store["createScope"]>[0]): Scope;
+    createTask(input: Parameters<Store["createTask"]>[0]): Task;
+    /** Approves a scope so its tasks become dispatchable (§8, §10 plan review). */
+    approveScope(scopeId: string): void;
+    /** Approves every proposed scope of a goal (`orc approve <goal-id>`, §9). */
+    approveGoal(goalId: string): Scope[];
+    /**
+     * Runs the Planner for a goal and materializes its Plan into proposed scopes
+     * and pending tasks, ready for operator approval. The plan is inert until
+     * approved — nothing dispatches here (§3: the Planner never dispatches).
+     */
+    planGoal(goalId: string): Promise<{
+        scopes: Scope[];
+        tasks: Task[];
+    }>;
+    /**
+     * Replaces a goal's proposed plan with an edited one (`orc plan edit`, §9).
+     * Validates the candidate, drops the existing proposed scopes/tasks, and
+     * re-materializes. Throws if validation fails so a bad edit never lands.
+     */
+    replacePlan(goalId: string, candidate: unknown): {
+        scopes: Scope[];
+        tasks: Task[];
+    };
+    /**
+     * Cancels a goal's proposed plan (§10 plan review): drops the proposed
+     * scopes and their tasks and returns the goal to `draft` so it can be
+     * re-planned. Approved/running scopes are never touched
+     * ({@link Store.deleteProposedPlan} only deletes `proposed` ones).
+     */
+    cancelPlan(goalId: string): void;
+    /**
+     * Applies a re-plan cycle's {@link Plan} additively — grows the goal's DAG
+     * without deleting existing scopes/tasks (autonomous-loop.md §3.3, G2). Used
+     * by the autonomous controller; the plan is already validated by the Planner.
+     * New scopes land `proposed`; the controller approves them per its mode.
+     */
+    applyReplan(goalId: string, plan: Plan): {
+        scopes: Scope[];
+        tasks: Task[];
+    };
+    /**
+     * Materializes a validated {@link Plan} into Scope/Task rows, resolving the
+     * plan's name-based `depends_on` references to the newly-minted ULIDs. Scopes
+     * land `proposed`, tasks `pending`; approval (per scope or per goal) flips
+     * scopes to `approved` so the dispatch loop can pick their tasks up.
+     *
+     * Thin wrapper over {@link appendPlan}: on the first materialization there are
+     * no existing scopes, so the two are equivalent.
+     */
+    private materializePlan;
+    /**
+     * Appends a validated {@link Plan}'s scopes/tasks to a goal WITHOUT deleting
+     * anything (autonomous-loop.md §3.3, G2). This is what a re-plan cycle uses to
+     * grow the DAG. Scope-level `depends_on` may reference either newly-created or
+     * pre-existing scope names, so a re-planned scope can depend on an
+     * already-completed one; on a name collision the new scope wins (consistent
+     * with intra-plan resolution). New scopes land `proposed`, tasks `pending`.
+     */
+    private appendPlan;
+    /** Starts a run for a goal and kicks the dispatch loop (§5). */
+    startRun(goalId: string, opts: {
+        budget_usd: number;
+        concurrency_limit?: number;
+        /** Feature-flow run (spec 002 §R5): auto-loops even with global config off. */
+        auto_loop?: boolean;
+    }): Run;
+    /**
+     * Graceful pause (§5): halt dispatch and interrupt running workers, waiting up
+     * to `pause.grace_ms` for them to yield at a tool-call boundary. Workers that
+     * do not settle within the grace window are marked `dirty` — resume will
+     * re-verify their workspace before continuing (§13.6).
+     */
+    pause(runId: string, reason?: string): Promise<void>;
+    /** A promise that resolves after `ms`, with an unref'd timer. */
+    private delay;
+    /**
+     * Resume (§5): re-queue every `paused` task so the dispatch loop picks it up
+     * again. Tasks that captured a `session_id` continue that session (SDK
+     * `resume:`) with a continuation prompt; the scope config is re-applied fresh
+     * so resume never inherits stale permissions. Then the run re-enters Running.
+     */
+    resume(runId: string): void;
+    /**
+     * Hard abort / kill switch (§5, §8.6): interrupt everything immediately and
+     * flag every in-flight task dirty — a hard stop may leave half-applied edits.
+     */
+    panic(runId: string): Promise<void>;
+    /** Number of workers currently in flight. */
+    get inFlight(): number;
+    /**
+     * Halts the dispatch loop for shutdown. Late worker `done` callbacks that fire
+     * after the store closes become no-ops, so nothing touches a closed database.
+     */
+    stop(): void;
+    /**
+     * One dispatch tick (§5). Selects ready tasks and spawns workers up to the
+     * concurrency limit. The budget gate is a single choke-point (§13.10): if the
+     * run is stopped, nothing new is dispatched.
+     */
+    tick(runId: string): Promise<void>;
+    private dependenciesMet;
+    private dispatch;
+    /**
+     * Reacts to a settled worker (§5, §13). A failure while the run is
+     * pausing/paused is an interrupt, not a real failure — the task is marked
+     * `paused` for resume. A genuine failure retries up to `retry.max_attempts`,
+     * feeding router R5 escalation, before it is left `failed`.
+     */
+    private onWorkerSettled;
+    /**
+     * Detects scope completion (autonomous-loop.md §3.2, G1). For each active
+     * scope whose tasks are all terminal, transitions it to `done` (none failed)
+     * or `failed` (≥1 failed after retries) and emits `scope.done`/`scope.failed`.
+     * A scope with no tasks, or holding a non-terminal task (queued/paused/
+     * blocked), is left untouched. Idempotent: already-terminal scopes are
+     * skipped, so this is safe to call after every worker settles.
+     */
+    private settleScopesFor;
+    /**
+     * Opt-in auto-merge of a settled scope branch into the run's base branch
+     * (spec 002 v2). Conservative by design: any skip (dirty checkout, wrong
+     * branch, conflict) leaves the branch for manual merge — the default flow.
+     * Every outcome is audited.
+     */
+    private maybeAutoMerge;
+    /**
+     * Detects a rate-limit signal in a worker failure (§7.4). If found, engages
+     * backpressure and re-queues the task without consuming a retry attempt — the
+     * dispatch gate holds it until the limit clears. Returns true when handled.
+     */
+    private handleLimitSignal;
+    /** Bounded retry (§5 `failed → queued`, §13). Requeues or gives up. */
+    private handleFailure;
+    private emitTaskState;
+    /** Registers the autonomous controller (autonomous-loop.md §3.1, G4). */
+    setAutoLoop(hook: AutoLoopHook): void;
+    private maybeFinish;
+    /**
+     * Marks a run terminal (done/failed), emits the transition, stops the interval
+     * timer, and writes the final report (§11). Used by `maybeFinish` and, in auto
+     * mode, by the controller when success criteria are satisfied.
+     */
+    finalizeRun(runId: string, state: "done" | "failed", reason?: string): void;
+    /**
+     * Parks an auto-loop run as `paused` with a reason (autonomous-loop.md §3.1):
+     * the runaway guards (`cycle_cap`, `no_progress`) and the supervised approval
+     * gate (`awaiting_replan_approval`) all land here. Non-terminal — an operator
+     * (or a mode change) can resume. Halts the dispatch loop via the run state.
+     */
+    parkRun(runId: string, reason: string): void;
+    private emitRunState;
+}
+//# sourceMappingURL=orchestrator.d.ts.map

package/dist/orchestrator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestrator.d.ts","sourceRoot":"","sources":["../src/orchestrator.ts"],"names":[],"mappings":"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"}