@harness-engineering/orchestrator 0.9.2 → 0.11.1

package/dist/index.d.mts

@@ -1,10 +1,11 @@
 import * as _harness_engineering_types from '@harness-engineering/types';
 import { Issue, AgentEvent, WorkflowConfig, TokenUsage, ConcernSignal, ScopeTier, EscalationConfig, IssueRoutingDecision, Result, WorkflowDefinition, BackendDef, RoutingConfig, WorkspaceConfig, HooksConfig, AgentBackend, SessionStartParams, AgentSession, AgentError, TurnParams, TurnResult, CheckScriptDefinition, OutputRetentionConfig, RoutingDecision, RoutingUseCase, ContainerConfig, SecretConfig, AgentConfig, LocalModelStatus, CustomTaskDefinition, MaintenanceConfig, TokenScope, AuthToken, AuthTokenPublic, IndexedFileKind, SessionSearchResult, ReindexStats, SessionSummarizationConfig, SessionSummary, SessionSummaryMeta, SessionsConfig, GatewayEvent, NotificationEnvelope, NotificationDeliveryResult, NotificationSinkConfig, NotificationsConfig } from '@harness-engineering/types';
-import { IssueTrackerClient, Issue as Issue$1, TrackerConfig, eventSourcing, CacheMetricsRecorder, ArchiveHooks, SkillProposal, ProposalGateFinding } from '@harness-engineering/core';
+import { IssueTrackerClient, Issue as Issue$1, TrackerConfig, eventSourcing, CacheMetricsRecorder, ArchiveHooks, SkillProposal, ProposalGateFinding, SkillKind } from '@harness-engineering/core';
 import { EnrichedSpec, ComplexityScore, SimulationResult, IntelligencePipeline, WeightedRecommendation, AnalysisProvider } from '@harness-engineering/intelligence';
 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 { z } from 'zod';
 
 /**
@@ -1697,6 +1698,45 @@ declare class Orchestrator extends EventEmitter {
      * so this map is the single source of truth post-migration.
      */
     private localResolvers;
+    /** Phase 4 (D5): pool-state port shared by all local/pi resolvers. Null when LMLM disabled. */
+    private poolStateProvider;
+    private poolStateStore;
+    /**
+     * LMLM Phase 6: live model pool + its installer. Constructed only when
+     * `localModels.enabled` and a real `PoolStateStore` exists (not a test
+     * override). Exposed to the server via `getModelPool()`, which retires the
+     * proposals-route 501 stub for `kind: 'model'` approve/reject. Null when LMLM
+     * is disabled. `PoolManager` reads `store.snapshot()` lazily, so constructing
+     * before `store.load()` (in initLocalModelAndPipeline) is safe.
+     */
+    private modelPool;
+    private modelInstaller;
+    /**
+     * S1 drain re-entrancy guard (P7-SUG-DRAIN-REENTRANCY). `drainDeferredEvictions`
+     * is fired fire-and-forget from `emitWorkerExit` (and, since P7-SUG-DRAIN-LIVENESS,
+     * piggybacked on each refresh tick). Two overlapping drains would both read the
+     * same `listPendingEvictions()` snapshot, both re-check `isLocalModelInUse`, and
+     * both `await pool.evict` the SAME name — double-calling the installer and
+     * broadcasting a duplicate `evict_completed` frame. The single-threaded event
+     * loop makes a plain boolean sufficient: a drain that arrives while one is
+     * running returns early rather than double-processing.
+     */
+    private draining;
+    /**
+     * LMLM Phase 6: single per-instance background refresh scheduler. Started in
+     * `initLocalModelAndPipeline` when the pool exists; stopped in `stop()`. Null
+     * when LMLM is disabled. Exposed to the server via `getRefreshScheduler()`.
+     */
+    private refreshScheduler;
+    /**
+     * LMLM Phase 7: the hardware-aware recommender bound at scheduler start. Reused
+     * by `GET /api/v1/local-models/recommendations`. Null when LMLM is disabled (no
+     * pool → scheduler never armed). Ranks the (currently empty) candidate set —
+     * see the Phase 2 candidate-parser gap noted on `startRefreshScheduler`.
+     */
+    private modelRecommender;
+    /** Test seam: injected timer/clock for the scheduler so no real 24h timer runs. */
+    private readonly schedulerTimerOverride;
     /**
      * Spec B Phase 3: skill catalog (name + cognitiveMode) read once at
      * construction from `projectRoot/agents/skills/`. Consulted by
@@ -1765,6 +1805,14 @@ declare class Orchestrator extends EventEmitter {
         tracker?: IssueTrackerClient;
         backend?: AgentBackend;
         execFileFn?: ExecFileFn$1;
+        poolState?: PoolStateProvider;
+        /** LMLM Phase 6 test seam: inject the RefreshScheduler timer/clock. */
+        schedulerTimer?: {
+            setTimer?: (cb: () => void, delayMs: number) => SchedulerTimerHandle;
+            clearTimer?: (handle: SchedulerTimerHandle) => void;
+            now?: () => number;
+            random?: () => number;
+        };
     });
     /**
      * Phase 5: construct the OTLP/HTTP trace exporter and wire telemetry fanout.
@@ -1784,6 +1832,29 @@ declare class Orchestrator extends EventEmitter {
      * with its backendName + endpoint from the config.
      */
     private buildLocalModelStatuses;
+    /**
+     * S1 conservative in-use probe (ADR 0060). Returns `true` when ANY agent run
+     * is live AND `ollamaName` is a currently-resolved (or last-detected) local
+     * model — i.e. an agent could be routing inference to it right now.
+     *
+     * This signal is AGENT-RUN-COARSE, not per-request: `state.running` is keyed
+     * by GitHub issue (spawned agent runs), NOT by inference call, and no
+     * per-model request counter exists today. The probe therefore MAY OVER-DEFER
+     * (a swap waits until the pool is idle). Over-deferral is exactly S1's
+     * intended safe failure — never yank a model mid-request; occasionally wait
+     * longer than strictly necessary. A fine-grained per-request signal is an
+     * explicit deferred gap (ADR 0060).
+     */
+    private isLocalModelInUse;
+    /**
+     * S1 drain (ADR 0060): complete any eviction that was DEFERRED because its
+     * target was in use, now that the probe reports it idle. Best-effort — called
+     * from the run-completion path; it never blocks dispatch and swallows
+     * per-model errors (a failed or still-busy evict stays pending for the next
+     * drain). `pendingEviction` is a transient overlay, so a missed drain simply
+     * leaves the flag set until the next completion re-checks it.
+     */
+    private drainDeferredEvictions;
     private createTracker;
     /**
      * Creates a TaskRunner for the maintenance scheduler.
@@ -1914,6 +1985,40 @@ declare class Orchestrator extends EventEmitter {
      * before constructing the intelligence pipeline. Subscribes the dashboard
      * broadcast stub to status changes. Called exactly once from start().
      */
+    /**
+     * LMLM Phase 6: construct the live `PoolManager` (Ollama installer + the
+     * loaded pool-state store) and stash it for `getModelPool()`. Defensive
+     * config fallbacks: `ollamaEndpoint → http://localhost:11434`. The pool reads
+     * `store.snapshot()` lazily, so this runs safely at construction time before
+     * `store.load()`.
+     */
+    private initModelPool;
+    /**
+     * LMLM Phase 7 wiring: apply the operator's configured pool bounds (disk
+     * budget + org/family allowlist) from `localModels.pool` to the live pool.
+     * Called after `PoolStateStore.load()` so config wins over persisted bounds
+     * (D2, declarative precedence). No-op when the pool is null (LMLM disabled)
+     * or no `pool` block is configured, so it is safe to call unconditionally
+     * on the startup path.
+     */
+    private applyConfiguredPoolBounds;
+    /**
+     * LMLM Phase 6: arm the single background refresh scheduler over the live
+     * pool. No-op when LMLM is disabled (`modelPool` null). Each tick runs
+     * hardware→recommend→reconcile(D12 drift)→diff→emit→score-writeback.
+     *
+     * NOTE (deferred): the recommender is seeded with an empty candidate set —
+     * Phase 2's live-HF→RankerCandidate parser was never built, so autonomous
+     * swap-proposal discovery is out of scope here (flagged concern). The tick
+     * still performs F10 drift reconciliation, O1 logging, and re-ranks/dedups
+     * whatever candidates are supplied — the wiring is complete and candidate
+     * breadth is the only piece deferred to the Phase 2 recommender.
+     */
+    private startRefreshScheduler;
+    /** 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). */
+    private lmlmDedupSource;
     private initLocalModelAndPipeline;
     /**
      * Starts the polling loop and the internal HTTP server.
@@ -2337,6 +2442,13 @@ interface LocalModelResolverOptions {
     apiKey?: string;
     /** Normalized candidate list (already turned from string|string[] into string[]). */
     configured: string[];
+    /**
+     * Phase 4 (D5): optional read-only pool-state port. When provided, the
+     * candidate list derives from pool entries (currentScore desc → ollamaName)
+     * instead of `configured`. When absent (default), behavior is byte-identical
+     * to the pre-Phase-4 resolver.
+     */
+    poolState?: PoolStateProvider;
     /** Probe cadence in ms; default 30_000, minimum 1_000. */
     probeIntervalMs?: number;
     /**
@@ -2367,6 +2479,7 @@ declare class LocalModelResolver {
     private readonly endpoint;
     private readonly apiKey?;
     private readonly configured;
+    private readonly poolState?;
     private readonly probeIntervalMs;
     private readonly fetchModels;
     private readonly logger;
@@ -2391,6 +2504,12 @@ declare class LocalModelResolver {
     constructor(opts: LocalModelResolverOptions);
     resolveModel(): string | null;
     getStatus(): LocalModelStatus;
+    /**
+     * Effective candidate list. With a poolState port present the list derives
+     * from pool entries (currentScore desc → ollamaName); otherwise the static
+     * `configured` list is returned unchanged (byte-identical to pre-Phase-4).
+     */
+    private candidates;
     onStatusChange(handler: (status: LocalModelStatus) => void): () => void;
     probe(): Promise<LocalModelStatus>;
     private runProbe;
@@ -3520,7 +3639,7 @@ declare function promote(projectPath: string, proposalId: string, decidedBy: str
  */
 interface ProposalCreatedData {
     id: string;
-    kind: SkillProposal['kind'];
+    kind: SkillKind;
     name: string;
     targetSkill?: string;
     proposedBy: string;
@@ -3528,14 +3647,14 @@ interface ProposalCreatedData {
 }
 interface ProposalApprovedData {
     id: string;
-    kind: SkillProposal['kind'];
+    kind: SkillKind;
     name: string;
     targetSkill?: string;
     decidedBy: string;
 }
 interface ProposalRejectedData {
     id: string;
-    kind: SkillProposal['kind'];
+    kind: SkillKind;
     name: string;
     decidedBy: string;
     reason: string;

package/dist/index.d.ts

@@ -1,10 +1,11 @@
 import * as _harness_engineering_types from '@harness-engineering/types';
 import { Issue, AgentEvent, WorkflowConfig, TokenUsage, ConcernSignal, ScopeTier, EscalationConfig, IssueRoutingDecision, Result, WorkflowDefinition, BackendDef, RoutingConfig, WorkspaceConfig, HooksConfig, AgentBackend, SessionStartParams, AgentSession, AgentError, TurnParams, TurnResult, CheckScriptDefinition, OutputRetentionConfig, RoutingDecision, RoutingUseCase, ContainerConfig, SecretConfig, AgentConfig, LocalModelStatus, CustomTaskDefinition, MaintenanceConfig, TokenScope, AuthToken, AuthTokenPublic, IndexedFileKind, SessionSearchResult, ReindexStats, SessionSummarizationConfig, SessionSummary, SessionSummaryMeta, SessionsConfig, GatewayEvent, NotificationEnvelope, NotificationDeliveryResult, NotificationSinkConfig, NotificationsConfig } from '@harness-engineering/types';
-import { IssueTrackerClient, Issue as Issue$1, TrackerConfig, eventSourcing, CacheMetricsRecorder, ArchiveHooks, SkillProposal, ProposalGateFinding } from '@harness-engineering/core';
+import { IssueTrackerClient, Issue as Issue$1, TrackerConfig, eventSourcing, CacheMetricsRecorder, ArchiveHooks, SkillProposal, ProposalGateFinding, SkillKind } from '@harness-engineering/core';
 import { EnrichedSpec, ComplexityScore, SimulationResult, IntelligencePipeline, WeightedRecommendation, AnalysisProvider } from '@harness-engineering/intelligence';
 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 { z } from 'zod';
 
 /**
@@ -1697,6 +1698,45 @@ declare class Orchestrator extends EventEmitter {
      * so this map is the single source of truth post-migration.
      */
     private localResolvers;
+    /** Phase 4 (D5): pool-state port shared by all local/pi resolvers. Null when LMLM disabled. */
+    private poolStateProvider;
+    private poolStateStore;
+    /**
+     * LMLM Phase 6: live model pool + its installer. Constructed only when
+     * `localModels.enabled` and a real `PoolStateStore` exists (not a test
+     * override). Exposed to the server via `getModelPool()`, which retires the
+     * proposals-route 501 stub for `kind: 'model'` approve/reject. Null when LMLM
+     * is disabled. `PoolManager` reads `store.snapshot()` lazily, so constructing
+     * before `store.load()` (in initLocalModelAndPipeline) is safe.
+     */
+    private modelPool;
+    private modelInstaller;
+    /**
+     * S1 drain re-entrancy guard (P7-SUG-DRAIN-REENTRANCY). `drainDeferredEvictions`
+     * is fired fire-and-forget from `emitWorkerExit` (and, since P7-SUG-DRAIN-LIVENESS,
+     * piggybacked on each refresh tick). Two overlapping drains would both read the
+     * same `listPendingEvictions()` snapshot, both re-check `isLocalModelInUse`, and
+     * both `await pool.evict` the SAME name — double-calling the installer and
+     * broadcasting a duplicate `evict_completed` frame. The single-threaded event
+     * loop makes a plain boolean sufficient: a drain that arrives while one is
+     * running returns early rather than double-processing.
+     */
+    private draining;
+    /**
+     * LMLM Phase 6: single per-instance background refresh scheduler. Started in
+     * `initLocalModelAndPipeline` when the pool exists; stopped in `stop()`. Null
+     * when LMLM is disabled. Exposed to the server via `getRefreshScheduler()`.
+     */
+    private refreshScheduler;
+    /**
+     * LMLM Phase 7: the hardware-aware recommender bound at scheduler start. Reused
+     * by `GET /api/v1/local-models/recommendations`. Null when LMLM is disabled (no
+     * pool → scheduler never armed). Ranks the (currently empty) candidate set —
+     * see the Phase 2 candidate-parser gap noted on `startRefreshScheduler`.
+     */
+    private modelRecommender;
+    /** Test seam: injected timer/clock for the scheduler so no real 24h timer runs. */
+    private readonly schedulerTimerOverride;
     /**
      * Spec B Phase 3: skill catalog (name + cognitiveMode) read once at
      * construction from `projectRoot/agents/skills/`. Consulted by
@@ -1765,6 +1805,14 @@ declare class Orchestrator extends EventEmitter {
         tracker?: IssueTrackerClient;
         backend?: AgentBackend;
         execFileFn?: ExecFileFn$1;
+        poolState?: PoolStateProvider;
+        /** LMLM Phase 6 test seam: inject the RefreshScheduler timer/clock. */
+        schedulerTimer?: {
+            setTimer?: (cb: () => void, delayMs: number) => SchedulerTimerHandle;
+            clearTimer?: (handle: SchedulerTimerHandle) => void;
+            now?: () => number;
+            random?: () => number;
+        };
     });
     /**
      * Phase 5: construct the OTLP/HTTP trace exporter and wire telemetry fanout.
@@ -1784,6 +1832,29 @@ declare class Orchestrator extends EventEmitter {
      * with its backendName + endpoint from the config.
      */
     private buildLocalModelStatuses;
+    /**
+     * S1 conservative in-use probe (ADR 0060). Returns `true` when ANY agent run
+     * is live AND `ollamaName` is a currently-resolved (or last-detected) local
+     * model — i.e. an agent could be routing inference to it right now.
+     *
+     * This signal is AGENT-RUN-COARSE, not per-request: `state.running` is keyed
+     * by GitHub issue (spawned agent runs), NOT by inference call, and no
+     * per-model request counter exists today. The probe therefore MAY OVER-DEFER
+     * (a swap waits until the pool is idle). Over-deferral is exactly S1's
+     * intended safe failure — never yank a model mid-request; occasionally wait
+     * longer than strictly necessary. A fine-grained per-request signal is an
+     * explicit deferred gap (ADR 0060).
+     */
+    private isLocalModelInUse;
+    /**
+     * S1 drain (ADR 0060): complete any eviction that was DEFERRED because its
+     * target was in use, now that the probe reports it idle. Best-effort — called
+     * from the run-completion path; it never blocks dispatch and swallows
+     * per-model errors (a failed or still-busy evict stays pending for the next
+     * drain). `pendingEviction` is a transient overlay, so a missed drain simply
+     * leaves the flag set until the next completion re-checks it.
+     */
+    private drainDeferredEvictions;
     private createTracker;
     /**
      * Creates a TaskRunner for the maintenance scheduler.
@@ -1914,6 +1985,40 @@ declare class Orchestrator extends EventEmitter {
      * before constructing the intelligence pipeline. Subscribes the dashboard
      * broadcast stub to status changes. Called exactly once from start().
      */
+    /**
+     * LMLM Phase 6: construct the live `PoolManager` (Ollama installer + the
+     * loaded pool-state store) and stash it for `getModelPool()`. Defensive
+     * config fallbacks: `ollamaEndpoint → http://localhost:11434`. The pool reads
+     * `store.snapshot()` lazily, so this runs safely at construction time before
+     * `store.load()`.
+     */
+    private initModelPool;
+    /**
+     * LMLM Phase 7 wiring: apply the operator's configured pool bounds (disk
+     * budget + org/family allowlist) from `localModels.pool` to the live pool.
+     * Called after `PoolStateStore.load()` so config wins over persisted bounds
+     * (D2, declarative precedence). No-op when the pool is null (LMLM disabled)
+     * or no `pool` block is configured, so it is safe to call unconditionally
+     * on the startup path.
+     */
+    private applyConfiguredPoolBounds;
+    /**
+     * LMLM Phase 6: arm the single background refresh scheduler over the live
+     * pool. No-op when LMLM is disabled (`modelPool` null). Each tick runs
+     * hardware→recommend→reconcile(D12 drift)→diff→emit→score-writeback.
+     *
+     * NOTE (deferred): the recommender is seeded with an empty candidate set —
+     * Phase 2's live-HF→RankerCandidate parser was never built, so autonomous
+     * swap-proposal discovery is out of scope here (flagged concern). The tick
+     * still performs F10 drift reconciliation, O1 logging, and re-ranks/dedups
+     * whatever candidates are supplied — the wiring is complete and candidate
+     * breadth is the only piece deferred to the Phase 2 recommender.
+     */
+    private startRefreshScheduler;
+    /** 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). */
+    private lmlmDedupSource;
     private initLocalModelAndPipeline;
     /**
      * Starts the polling loop and the internal HTTP server.
@@ -2337,6 +2442,13 @@ interface LocalModelResolverOptions {
     apiKey?: string;
     /** Normalized candidate list (already turned from string|string[] into string[]). */
     configured: string[];
+    /**
+     * Phase 4 (D5): optional read-only pool-state port. When provided, the
+     * candidate list derives from pool entries (currentScore desc → ollamaName)
+     * instead of `configured`. When absent (default), behavior is byte-identical
+     * to the pre-Phase-4 resolver.
+     */
+    poolState?: PoolStateProvider;
     /** Probe cadence in ms; default 30_000, minimum 1_000. */
     probeIntervalMs?: number;
     /**
@@ -2367,6 +2479,7 @@ declare class LocalModelResolver {
     private readonly endpoint;
     private readonly apiKey?;
     private readonly configured;
+    private readonly poolState?;
     private readonly probeIntervalMs;
     private readonly fetchModels;
     private readonly logger;
@@ -2391,6 +2504,12 @@ declare class LocalModelResolver {
     constructor(opts: LocalModelResolverOptions);
     resolveModel(): string | null;
     getStatus(): LocalModelStatus;
+    /**
+     * Effective candidate list. With a poolState port present the list derives
+     * from pool entries (currentScore desc → ollamaName); otherwise the static
+     * `configured` list is returned unchanged (byte-identical to pre-Phase-4).
+     */
+    private candidates;
     onStatusChange(handler: (status: LocalModelStatus) => void): () => void;
     probe(): Promise<LocalModelStatus>;
     private runProbe;
@@ -3520,7 +3639,7 @@ declare function promote(projectPath: string, proposalId: string, decidedBy: str
  */
 interface ProposalCreatedData {
     id: string;
-    kind: SkillProposal['kind'];
+    kind: SkillKind;
     name: string;
     targetSkill?: string;
     proposedBy: string;
@@ -3528,14 +3647,14 @@ interface ProposalCreatedData {
 }
 interface ProposalApprovedData {
     id: string;
-    kind: SkillProposal['kind'];
+    kind: SkillKind;
     name: string;
     targetSkill?: string;
     decidedBy: string;
 }
 interface ProposalRejectedData {
     id: string;
-    kind: SkillProposal['kind'];
+    kind: SkillKind;
     name: string;
     decidedBy: string;
     reason: string;