@ashlr/hub 2.2.0

package/dist/core/run/orchestrator.d.ts

@@ -0,0 +1,100 @@
+/**
+ * core/run/orchestrator.ts — M4/M11/M15 local-first agent orchestrator.
+ *
+ * Responsibilities:
+ *  - planGoal:  single chat call -> RunTask[] DAG (1-6 tasks, deps valid).
+ *  - runGoal:   resolve client, plan/resume, execute DAG (parallel up to opts.parallel),
+ *               enforce HARD budget, persist RunState after every step, synthesize
+ *               final answer, best-effort Pulse POST.
+ *  - loadRun / listRuns / saveRun: JSON persistence under ~/.ashlr/runs/.
+ *
+ * M7 addition: genome-aware injection. Before planning, runGoal calls
+ * recall(goal, cfg) from src/core/genome/recall.ts (dynamic import, best-effort)
+ * and prepends a bounded "Relevant project memory:" block to the planning system
+ * prompt so the planner starts with relevant cross-project context.
+ * Gated on cfg.genome?.injectOnRun (default true) and opts.noMemory (opt-out).
+ * Never throws — if recall fails or is empty, the run proceeds unchanged.
+ *
+ * M16 addition: playbook injection + auto-capture.
+ *  - Planning injection: when cfg.genome?.playbookOnRun !== false and !noMemory,
+ *    builds a synthesized playbook via genome/playbook.buildPlaybook (dynamic import,
+ *    best-effort) and injects playbookText(...) instead of raw recall. Falls back to
+ *    the existing raw-recall block on any playbook failure.
+ *  - Auto-capture: after final state is persisted, calls captureFromRun (fire-and-
+ *    forget) from genome/capture.ts. Disabled via opts.noCapture or
+ *    cfg.genome?.autoCapture === false. Never throws, never blocks.
+ *
+ * M11 additions:
+ *  - HARDENED ENGINE DELEGATION: buildEngineCommand + spawnEngine (engines.ts)
+ *    replace the guessed ['--goal',goal] spawn. Per-engine adapters produce
+ *    correct argv; phantom-exec wraps when cfg.phantom?.enabled.
+ *  - STREAMING: StreamSink threaded from CLI (__sink on opts) through runGoal
+ *    → runTask → agent loop. Events: task-start/model-delta/tool-call/task-done/
+ *    retry/verify/log. nullSink used when absent.
+ *  - RETRY: per-task withRetry (bounded, budget-aware) on tool/transient failures.
+ *  - VERIFY: verifyTask after each builtin task; one retry on !ok if budget allows;
+ *    else annotates result with [needs-attention].
+ *
+ * M15 additions:
+ *  - PER-TASK ROUTING: before each task attempt, chooseRoute() selects the best
+ *    LOCAL provider+model (or cloud when allowCloud + key + escalation reason).
+ *    Dynamic import of router.ts — best-effort; falls back to getActiveClient when
+ *    the module is absent (preserves pre-M15 behavior in the build pipeline).
+ *  - AUTO-ESCALATE: on task failure or verify !ok, if allowCloud is set AND a cloud
+ *    key is present, ONE escalated routed retry is attempted. Otherwise stays local
+ *    and marks needs-attention. Gated exactly by chooseRoute's guardrails.
+ *  - COST ATTRIBUTION: estCostUsd uses the per-task RouteDecision.provider so local
+ *    tasks always cost $0 and cloud escalations are estimated correctly.
+ *
+ * Safety guardrails (binding):
+ *  - Never writes outside ~/.ashlr/runs/ — no repos/Desktop, no git.
+ *  - Budget is a HARD ceiling (aborts with partial results preserved).
+ *  - Cloud endpoints require explicit allowCloud + key present (delegated to
+ *    getActiveClient / chooseRoute). NO SILENT CLOUD SPEND.
+ *  - Zero new runtime deps (Node builtins + @modelcontextprotocol/sdk only).
+ *  - Genome recall is local-only (keyword/TF-IDF, optional local Ollama embeddings).
+ *  - Engine delegation is a single bounded spawn — never recursive.
+ *  - NO AUTO-DOWNLOAD: ollama pull is never called from routing or runs.
+ */
+import type { AshlrConfig, RunTask, RunState, RunOptions, ProviderClient } from '../types.js';
+/** Default token budget per run. */
+export declare const DEFAULT_MAX_TOKENS = 50000;
+/** Default step budget per run. */
+export declare const DEFAULT_MAX_STEPS = 40;
+/** Default parallel task execution limit. */
+export declare const DEFAULT_PARALLEL = 2;
+/**
+ * Load a persisted RunState by id. Returns null if absent, unreadable, or invalid JSON.
+ */
+export declare function loadRun(id: string): RunState | null;
+/**
+ * List all persisted runs, newest first by createdAt.
+ */
+export declare function listRuns(): RunState[];
+/**
+ * Atomically persist a RunState to ~/.ashlr/runs/<id>.json (write-then-rename).
+ * ONLY writes under runsDir() — never touches repos or Desktop.
+ */
+export declare function saveRun(s: RunState): void;
+/**
+ * Planning call: ask the model to decompose `goal` into a RunTask[] DAG.
+ * Falls back to a single task whose goal is the original goal on parse failure.
+ *
+ * @param memoryContext Optional genome memory block to prepend to the system prompt.
+ *   When non-empty, injects "Relevant project memory:" context so the planner
+ *   benefits from cross-project knowledge. Kept bounded upstream (GENOME_INJECT_CHAR_CAP).
+ */
+export declare function planGoal(goal: string, client: ProviderClient, onUsage?: (usage: {
+    tokensIn: number;
+    tokensOut: number;
+}) => void, memoryContext?: string): Promise<RunTask[]>;
+/**
+ * Top-level orchestrator driver. Builds/loads RunState, plans (unless resuming),
+ * executes the DAG with parallelism up to opts.parallel, enforces HARD budget,
+ * persists after every step, synthesizes final answer, best-effort Pulse POST.
+ *
+ * M7: genome-aware. Before planning, recalls top-k genome hits for the goal
+ * and injects them as context into the planning prompt — bounded, local-only,
+ * best-effort. Disabled via opts.noMemory or cfg.genome?.injectOnRun === false.
+ */
+export declare function runGoal(goal: string, cfg: AshlrConfig, opts: RunOptions): Promise<RunState>;