@harness-engineering/orchestrator 0.11.1 → 0.12.0

package/dist/index.d.mts

@@ -5,7 +5,8 @@ import { EnrichedSpec, ComplexityScore, SimulationResult, IntelligencePipeline,
 import { GraphStore } from '@harness-engineering/graph';
 import { execFile } from 'node:child_process';
 import { EventEmitter } from 'node:events';
-import { PoolStateProvider, SchedulerTimerHandle } from '@harness-engineering/local-models';
+import { PoolStateProvider, SchedulerTimerHandle, DiscoverCandidatesOptions, DiscoverCandidatesResult } from '@harness-engineering/local-models';
+export { discoverCandidates } from '@harness-engineering/local-models';
 import { z } from 'zod';
 
 /**
@@ -1698,6 +1699,13 @@ declare class Orchestrator extends EventEmitter {
      * so this map is the single source of truth post-migration.
      */
     private localResolvers;
+    /**
+     * Consumption Phase 1 (T2): bus listener that debounce-refreshes every local
+     * resolver when a `local-models:pool` mutation fires, so a just-installed or
+     * swapped model becomes usable within the refresh window instead of waiting up
+     * to `probeIntervalMs` for the next poll. Held for removal in {@link stop}.
+     */
+    private poolRefreshListener;
     /** Phase 4 (D5): pool-state port shared by all local/pi resolvers. Null when LMLM disabled. */
     private poolStateProvider;
     private poolStateStore;
@@ -1735,6 +1743,10 @@ declare class Orchestrator extends EventEmitter {
      * see the Phase 2 candidate-parser gap noted on `startRefreshScheduler`.
      */
     private modelRecommender;
+    /** Live HF candidate discovery (injectable for tests so startup makes no network calls). */
+    private readonly discoverCandidatesFn;
+    /** Snapshot of the last candidate seeding, surfaced to the refresh route. */
+    private candidateSourceState;
     /** Test seam: injected timer/clock for the scheduler so no real 24h timer runs. */
     private readonly schedulerTimerOverride;
     /**
@@ -1813,6 +1825,8 @@ declare class Orchestrator extends EventEmitter {
             now?: () => number;
             random?: () => number;
         };
+        /** Live-candidate-discovery seam: tests inject a fake so startup makes no HF calls. */
+        discoverCandidates?: (opts: DiscoverCandidatesOptions) => Promise<DiscoverCandidatesResult>;
     });
     /**
      * Phase 5: construct the OTLP/HTTP trace exporter and wire telemetry fanout.
@@ -1993,6 +2007,14 @@ declare class Orchestrator extends EventEmitter {
      * `store.load()`.
      */
     private initModelPool;
+    /**
+     * Resume installs interrupted by a restart. A proposal left `installing` had
+     * its background `ollama pull` cut short when the orchestrator went down; the
+     * pull is idempotent (ollama resumes from cached blobs), so we re-drive it.
+     * Fire-and-forget with its own error isolation — a resumed multi-GB download
+     * must not block startup, and a re-drive failure only logs.
+     */
+    private redriveInterruptedInstalls;
     /**
      * LMLM Phase 7 wiring: apply the operator's configured pool bounds (disk
      * budget + org/family allowlist) from `localModels.pool` to the live pool.
@@ -2015,6 +2037,17 @@ declare class Orchestrator extends EventEmitter {
      * breadth is the only piece deferred to the Phase 2 recommender.
      */
     private startRefreshScheduler;
+    /** (Re)build the recommender over `candidates` and record the seeding source. */
+    private seedRecommender;
+    /**
+     * Refresh ranking candidates live from HuggingFace, merge the curated
+     * `ollamaName`/`family` tags from the frozen snapshot (so results stay
+     * installable — decision A), and re-seed the recommender. Fail-closed: on any
+     * error or an empty installable result, the current candidates stand. Runs a
+     * `forceRefresh` tick so recommendations + proposals reflect the fresh set.
+     * Used by both the startup background refresh and the operator "Refresh" button.
+     */
+    private refreshCandidatesLive;
     /** Resolve the hardware profile for a refresh tick (operator override wins). */
     private detectLmlmHardware;
     /** Map the on-disk model-proposal queue to F7 dedup pairs (open→pending, rejected→rejected). */
@@ -2087,6 +2120,16 @@ declare function launchTUI(orchestrator: Orchestrator): {
  * `LocalModelResolver` (so multi-resolver array-fallback works without
  * leaking resolver lifetimes into the factory).
  */
+/**
+ * Runtime-feedback callbacks a `local`/`pi` backend fires as turns complete.
+ * See {@link OrchestratorBackendFactoryOptions.getModelUsageHooksFor}.
+ */
+interface LocalModelUsageHooks {
+    /** Fired with the resolved model after a successful turn (LRU + breaker clear). */
+    onModelUsed?: (model: string) => void;
+    /** Fired with the resolved model after a failed turn (breaker increment). */
+    onModelFailed?: (model: string) => void;
+}
 interface OrchestratorBackendFactoryOptions {
     backends: Record<string, BackendDef>;
     routing: RoutingConfig;
@@ -2105,7 +2148,17 @@ interface OrchestratorBackendFactoryOptions {
      * existence and lifecycle while still letting it produce backends that
      * route through the resolver Map.
      */
-    getResolverModelFor?: (backendName: string) => (() => string | null) | undefined;
+    getResolverModelFor?: (backendName: string, useCase: RoutingUseCase) => (() => string | null) | undefined;
+    /**
+     * Consumption Phase 3 (T11): per-`local`/`pi` backend hook returning the
+     * runtime-feedback callbacks bound to that backend's resolver + pool. The
+     * factory forwards them to the constructed `LocalBackend` so a completed turn
+     * stamps `lastUsedAt` (LRU) + clears the circuit breaker, and a failed turn
+     * feeds the breaker. Returning `undefined` means "no feedback wiring" (the
+     * backend runs exactly as before). Kept parallel to `getResolverModelFor` so
+     * the factory stays ignorant of resolver/pool lifecycles.
+     */
+    getModelUsageHooksFor?: (backendName: string) => LocalModelUsageHooks | undefined;
     /**
      * Phase 5: prompt-cache recorder forwarded to Anthropic-capable backends.
      * Other backends accept-but-ignore. Shared across dispatches so the
@@ -2451,6 +2504,26 @@ interface LocalModelResolverOptions {
     poolState?: PoolStateProvider;
     /** Probe cadence in ms; default 30_000, minimum 1_000. */
     probeIntervalMs?: number;
+    /** Debounce window for event-driven {@link LocalModelResolver.refresh}; default 250ms. */
+    refreshDebounceMs?: number;
+    /**
+     * Consumption Phase 5 (T19/T20): called with the newly-resolved model name
+     * whenever the resolver's composite selection changes (and is non-null), so
+     * the orchestrator can warm it into VRAM before the next dispatch. Naturally
+     * debounced — it fires only on an actual selection change, not every probe.
+     * Best-effort: a throwing hook is swallowed. Injected in tests; wired to
+     * {@link defaultWarmModel} in production.
+     */
+    warmModel?: (ollamaName: string) => void;
+    /**
+     * Consumption Phase 3 (T10): consecutive inference failures before a model is
+     * deprioritized by the circuit breaker. Default 3.
+     */
+    breakerThreshold?: number;
+    /** Cooldown (ms) after which a tripped model is eligible again. Default 60_000. */
+    breakerCooldownMs?: number;
+    /** Injectable clock (ms since epoch) for the circuit-breaker cooldown; default `Date.now`. Test seam. */
+    now?: () => number;
     /**
      * Per-request timeout for the default fetch implementation, in ms.
      * Default: 5_000. Ignored when a custom `fetchModels` is provided
@@ -2482,8 +2555,21 @@ declare class LocalModelResolver {
     private readonly poolState?;
     private readonly probeIntervalMs;
     private readonly fetchModels;
+    private readonly warmModel?;
     private readonly logger;
     private timer;
+    /** Debounce handle for event-driven {@link refresh}; coalesces a burst into one probe. */
+    private refreshTimer;
+    /** Test seam for the refresh debounce delay (0 in tests → next-tick probe). */
+    private readonly refreshDebounceMs;
+    /** Consumption Phase 3 (T10): circuit-breaker config + per-model failure/trip state. */
+    private readonly breakerThreshold;
+    private readonly breakerCooldownMs;
+    private readonly now;
+    /** Consecutive inference failures per model since its last success. */
+    private consecutiveFailures;
+    /** Epoch-ms at which a tripped model becomes eligible again (cooldown expiry). */
+    private trippedUntil;
     private listeners;
     /**
      * Tracks an in-flight probe so concurrent invocations (interval tick while a
@@ -2502,7 +2588,15 @@ declare class LocalModelResolver {
     private warnings;
     private available;
     constructor(opts: LocalModelResolverOptions);
-    resolveModel(): string | null;
+    /**
+     * The model to dispatch to. With no `useCase`, returns the cached composite
+     * resolution from the last probe (byte-identical to the pre-Phase-4 resolver).
+     * With a `useCase`, orders the (pool-derived) candidates by that use-case's
+     * task profile and picks the best loaded, breaker-healthy one — so a
+     * coding-tagged dispatch prefers the coding specialist. A `general`-mapped
+     * use-case returns the cached composite resolution unchanged.
+     */
+    resolveModel(useCase?: RoutingUseCase): string | null;
     getStatus(): LocalModelStatus;
     /**
      * Effective candidate list. With a poolState port present the list derives
@@ -2513,6 +2607,41 @@ declare class LocalModelResolver {
     onStatusChange(handler: (status: LocalModelStatus) => void): () => void;
     probe(): Promise<LocalModelStatus>;
     private runProbe;
+    /** Best-effort warm-hook invocation — a throwing warm never breaks a probe. */
+    private warm;
+    /**
+     * Consumption Phase 3 (T10): pick the resolved model from the candidates that
+     * are actually loaded, preferring ones whose circuit breaker is not tripped.
+     * Candidate order (score-desc from the pool) is preserved within each tier, so
+     * a tripped top pick sinks below a healthy lower pick but still resolves as a
+     * last resort when every loaded candidate is tripped (better a flaky model than
+     * none). Returns null when no candidate is loaded.
+     */
+    private selectMatch;
+    /**
+     * Whether `model`'s circuit breaker is currently tripped. Lazily clears the
+     * trip once its cooldown has elapsed so the model becomes eligible again on the
+     * next resolution without needing a separate timer.
+     */
+    private isTripped;
+    /**
+     * Record a successful inference on `model`: clears its failure count and any
+     * active trip so a recovered model is immediately re-preferred.
+     */
+    recordSuccess(model: string): void;
+    /**
+     * Record a failed inference on `model`. On the Nth consecutive failure the
+     * breaker trips (deprioritizing the model for `breakerCooldownMs`) and a
+     * re-probe is scheduled so the resolver rolls to a healthy alternative.
+     */
+    recordFailure(model: string): void;
+    /**
+     * Event-driven refresh: schedule a debounced re-probe. Called when a
+     * `local-models:pool` mutation fires so a just-installed/swapped model becomes
+     * usable within a debounce window instead of waiting up to `probeIntervalMs`.
+     * A burst of frames coalesces into one probe (the timer is only armed once).
+     */
+    refresh(): void;
     start(): Promise<void>;
     stop(): void;
     private snapshotForDiff;

package/dist/index.d.ts

@@ -5,7 +5,8 @@ import { EnrichedSpec, ComplexityScore, SimulationResult, IntelligencePipeline,
 import { GraphStore } from '@harness-engineering/graph';
 import { execFile } from 'node:child_process';
 import { EventEmitter } from 'node:events';
-import { PoolStateProvider, SchedulerTimerHandle } from '@harness-engineering/local-models';
+import { PoolStateProvider, SchedulerTimerHandle, DiscoverCandidatesOptions, DiscoverCandidatesResult } from '@harness-engineering/local-models';
+export { discoverCandidates } from '@harness-engineering/local-models';
 import { z } from 'zod';
 
 /**
@@ -1698,6 +1699,13 @@ declare class Orchestrator extends EventEmitter {
      * so this map is the single source of truth post-migration.
      */
     private localResolvers;
+    /**
+     * Consumption Phase 1 (T2): bus listener that debounce-refreshes every local
+     * resolver when a `local-models:pool` mutation fires, so a just-installed or
+     * swapped model becomes usable within the refresh window instead of waiting up
+     * to `probeIntervalMs` for the next poll. Held for removal in {@link stop}.
+     */
+    private poolRefreshListener;
     /** Phase 4 (D5): pool-state port shared by all local/pi resolvers. Null when LMLM disabled. */
     private poolStateProvider;
     private poolStateStore;
@@ -1735,6 +1743,10 @@ declare class Orchestrator extends EventEmitter {
      * see the Phase 2 candidate-parser gap noted on `startRefreshScheduler`.
      */
     private modelRecommender;
+    /** Live HF candidate discovery (injectable for tests so startup makes no network calls). */
+    private readonly discoverCandidatesFn;
+    /** Snapshot of the last candidate seeding, surfaced to the refresh route. */
+    private candidateSourceState;
     /** Test seam: injected timer/clock for the scheduler so no real 24h timer runs. */
     private readonly schedulerTimerOverride;
     /**
@@ -1813,6 +1825,8 @@ declare class Orchestrator extends EventEmitter {
             now?: () => number;
             random?: () => number;
         };
+        /** Live-candidate-discovery seam: tests inject a fake so startup makes no HF calls. */
+        discoverCandidates?: (opts: DiscoverCandidatesOptions) => Promise<DiscoverCandidatesResult>;
     });
     /**
      * Phase 5: construct the OTLP/HTTP trace exporter and wire telemetry fanout.
@@ -1993,6 +2007,14 @@ declare class Orchestrator extends EventEmitter {
      * `store.load()`.
      */
     private initModelPool;
+    /**
+     * Resume installs interrupted by a restart. A proposal left `installing` had
+     * its background `ollama pull` cut short when the orchestrator went down; the
+     * pull is idempotent (ollama resumes from cached blobs), so we re-drive it.
+     * Fire-and-forget with its own error isolation — a resumed multi-GB download
+     * must not block startup, and a re-drive failure only logs.
+     */
+    private redriveInterruptedInstalls;
     /**
      * LMLM Phase 7 wiring: apply the operator's configured pool bounds (disk
      * budget + org/family allowlist) from `localModels.pool` to the live pool.
@@ -2015,6 +2037,17 @@ declare class Orchestrator extends EventEmitter {
      * breadth is the only piece deferred to the Phase 2 recommender.
      */
     private startRefreshScheduler;
+    /** (Re)build the recommender over `candidates` and record the seeding source. */
+    private seedRecommender;
+    /**
+     * Refresh ranking candidates live from HuggingFace, merge the curated
+     * `ollamaName`/`family` tags from the frozen snapshot (so results stay
+     * installable — decision A), and re-seed the recommender. Fail-closed: on any
+     * error or an empty installable result, the current candidates stand. Runs a
+     * `forceRefresh` tick so recommendations + proposals reflect the fresh set.
+     * Used by both the startup background refresh and the operator "Refresh" button.
+     */
+    private refreshCandidatesLive;
     /** Resolve the hardware profile for a refresh tick (operator override wins). */
     private detectLmlmHardware;
     /** Map the on-disk model-proposal queue to F7 dedup pairs (open→pending, rejected→rejected). */
@@ -2087,6 +2120,16 @@ declare function launchTUI(orchestrator: Orchestrator): {
  * `LocalModelResolver` (so multi-resolver array-fallback works without
  * leaking resolver lifetimes into the factory).
  */
+/**
+ * Runtime-feedback callbacks a `local`/`pi` backend fires as turns complete.
+ * See {@link OrchestratorBackendFactoryOptions.getModelUsageHooksFor}.
+ */
+interface LocalModelUsageHooks {
+    /** Fired with the resolved model after a successful turn (LRU + breaker clear). */
+    onModelUsed?: (model: string) => void;
+    /** Fired with the resolved model after a failed turn (breaker increment). */
+    onModelFailed?: (model: string) => void;
+}
 interface OrchestratorBackendFactoryOptions {
     backends: Record<string, BackendDef>;
     routing: RoutingConfig;
@@ -2105,7 +2148,17 @@ interface OrchestratorBackendFactoryOptions {
      * existence and lifecycle while still letting it produce backends that
      * route through the resolver Map.
      */
-    getResolverModelFor?: (backendName: string) => (() => string | null) | undefined;
+    getResolverModelFor?: (backendName: string, useCase: RoutingUseCase) => (() => string | null) | undefined;
+    /**
+     * Consumption Phase 3 (T11): per-`local`/`pi` backend hook returning the
+     * runtime-feedback callbacks bound to that backend's resolver + pool. The
+     * factory forwards them to the constructed `LocalBackend` so a completed turn
+     * stamps `lastUsedAt` (LRU) + clears the circuit breaker, and a failed turn
+     * feeds the breaker. Returning `undefined` means "no feedback wiring" (the
+     * backend runs exactly as before). Kept parallel to `getResolverModelFor` so
+     * the factory stays ignorant of resolver/pool lifecycles.
+     */
+    getModelUsageHooksFor?: (backendName: string) => LocalModelUsageHooks | undefined;
     /**
      * Phase 5: prompt-cache recorder forwarded to Anthropic-capable backends.
      * Other backends accept-but-ignore. Shared across dispatches so the
@@ -2451,6 +2504,26 @@ interface LocalModelResolverOptions {
     poolState?: PoolStateProvider;
     /** Probe cadence in ms; default 30_000, minimum 1_000. */
     probeIntervalMs?: number;
+    /** Debounce window for event-driven {@link LocalModelResolver.refresh}; default 250ms. */
+    refreshDebounceMs?: number;
+    /**
+     * Consumption Phase 5 (T19/T20): called with the newly-resolved model name
+     * whenever the resolver's composite selection changes (and is non-null), so
+     * the orchestrator can warm it into VRAM before the next dispatch. Naturally
+     * debounced — it fires only on an actual selection change, not every probe.
+     * Best-effort: a throwing hook is swallowed. Injected in tests; wired to
+     * {@link defaultWarmModel} in production.
+     */
+    warmModel?: (ollamaName: string) => void;
+    /**
+     * Consumption Phase 3 (T10): consecutive inference failures before a model is
+     * deprioritized by the circuit breaker. Default 3.
+     */
+    breakerThreshold?: number;
+    /** Cooldown (ms) after which a tripped model is eligible again. Default 60_000. */
+    breakerCooldownMs?: number;
+    /** Injectable clock (ms since epoch) for the circuit-breaker cooldown; default `Date.now`. Test seam. */
+    now?: () => number;
     /**
      * Per-request timeout for the default fetch implementation, in ms.
      * Default: 5_000. Ignored when a custom `fetchModels` is provided
@@ -2482,8 +2555,21 @@ declare class LocalModelResolver {
     private readonly poolState?;
     private readonly probeIntervalMs;
     private readonly fetchModels;
+    private readonly warmModel?;
     private readonly logger;
     private timer;
+    /** Debounce handle for event-driven {@link refresh}; coalesces a burst into one probe. */
+    private refreshTimer;
+    /** Test seam for the refresh debounce delay (0 in tests → next-tick probe). */
+    private readonly refreshDebounceMs;
+    /** Consumption Phase 3 (T10): circuit-breaker config + per-model failure/trip state. */
+    private readonly breakerThreshold;
+    private readonly breakerCooldownMs;
+    private readonly now;
+    /** Consecutive inference failures per model since its last success. */
+    private consecutiveFailures;
+    /** Epoch-ms at which a tripped model becomes eligible again (cooldown expiry). */
+    private trippedUntil;
     private listeners;
     /**
      * Tracks an in-flight probe so concurrent invocations (interval tick while a
@@ -2502,7 +2588,15 @@ declare class LocalModelResolver {
     private warnings;
     private available;
     constructor(opts: LocalModelResolverOptions);
-    resolveModel(): string | null;
+    /**
+     * The model to dispatch to. With no `useCase`, returns the cached composite
+     * resolution from the last probe (byte-identical to the pre-Phase-4 resolver).
+     * With a `useCase`, orders the (pool-derived) candidates by that use-case's
+     * task profile and picks the best loaded, breaker-healthy one — so a
+     * coding-tagged dispatch prefers the coding specialist. A `general`-mapped
+     * use-case returns the cached composite resolution unchanged.
+     */
+    resolveModel(useCase?: RoutingUseCase): string | null;
     getStatus(): LocalModelStatus;
     /**
      * Effective candidate list. With a poolState port present the list derives
@@ -2513,6 +2607,41 @@ declare class LocalModelResolver {
     onStatusChange(handler: (status: LocalModelStatus) => void): () => void;
     probe(): Promise<LocalModelStatus>;
     private runProbe;
+    /** Best-effort warm-hook invocation — a throwing warm never breaks a probe. */
+    private warm;
+    /**
+     * Consumption Phase 3 (T10): pick the resolved model from the candidates that
+     * are actually loaded, preferring ones whose circuit breaker is not tripped.
+     * Candidate order (score-desc from the pool) is preserved within each tier, so
+     * a tripped top pick sinks below a healthy lower pick but still resolves as a
+     * last resort when every loaded candidate is tripped (better a flaky model than
+     * none). Returns null when no candidate is loaded.
+     */
+    private selectMatch;
+    /**
+     * Whether `model`'s circuit breaker is currently tripped. Lazily clears the
+     * trip once its cooldown has elapsed so the model becomes eligible again on the
+     * next resolution without needing a separate timer.
+     */
+    private isTripped;
+    /**
+     * Record a successful inference on `model`: clears its failure count and any
+     * active trip so a recovered model is immediately re-preferred.
+     */
+    recordSuccess(model: string): void;
+    /**
+     * Record a failed inference on `model`. On the Nth consecutive failure the
+     * breaker trips (deprioritizing the model for `breakerCooldownMs`) and a
+     * re-probe is scheduled so the resolver rolls to a healthy alternative.
+     */
+    recordFailure(model: string): void;
+    /**
+     * Event-driven refresh: schedule a debounced re-probe. Called when a
+     * `local-models:pool` mutation fires so a just-installed/swapped model becomes
+     * usable within a debounce window instead of waiting up to `probeIntervalMs`.
+     * A burst of frames coalesces into one probe (the timer is only armed once).
+     */
+    refresh(): void;
     start(): Promise<void>;
     stop(): void;
     private snapshotForDiff;