Skip to content

A desktop coding agent with free access to frontier models.

TypeScript
9.0 KB
Raw Blame
/**
 * Idle eviction for per-directory OpenCode engine instances.
 *
 * The managed engine is one long-lived process that boots a per-directory
 * instance on demand and never retires one on its own. Since the continuous
 * engine keeps that process alive across workspace switches, every workspace
 * ever visited retains a live instance — config, plugins, watchers, session
 * caches — for the lifetime of the app. This reaper reclaims those instances.
 *
 * Policy: an instance is evicted only when every hold is absent —
 * - it is not the active workspace's instance,
 * - no engine event stream from that workspace is open (no visible UI),
 * - it reports no non-idle session (a live background run always stays), and
 * - it has seen no traffic for the idle TTL.
 *
 * Sessions live in the engine's shared SQLite, so an evicted instance loses
 * only process state. The next request re-materializes it from disk config;
 * the server owns pushing back the runtime-DB MCPs a fresh instance cannot
 * read from disk, which is why eviction marks the workspace and `noteUsed`
 * reports that mark exactly once to whoever sends the next traffic.
 *
 * Only managed engines are swept: an attached engine may serve other clients,
 * so its instances are not ours to trim. The hooks own every side effect; this
 * module holds the policy and its bookkeeping.
 */
import type { ServerConfig } from "./types.js";

export type EngineInstanceReaperLogger = {
  log: (level: "info" | "warn" | "error", message: string, attributes?: Record<string, unknown>) => void;
};

export type EngineInstanceUse = {
  directory: string;
  workspaceId: string;
  engineBaseUrl: string;
};

export type TrackedEngineInstance = EngineInstanceUse & {
  lastUsedAt: number;
  streamHolds: number;
};

export type EngineInstanceReaperHooks = {
  /** Primary managed engine URL. Null means no managed engine: nothing is swept. */
  engineBaseUrl: () => string | null;
  /** Directory of the active local workspace. Its instance always stays warm. */
  activeDirectory: () => string | null;
  /** True when the instance still reports a non-idle session. A thrown error means unknown, which never evicts. */
  directoryBusy: (instance: TrackedEngineInstance) => Promise<boolean>;
  /** Dispose the instance and invalidate whatever per-workspace evidence a fresh instance cannot honor. */
  dispose: (instance: TrackedEngineInstance) => Promise<void>;
  now?: () => number;
  logger?: EngineInstanceReaperLogger;
};

/** How long an instance may sit unused before it is eligible for eviction. 0 disables eviction. */
export function engineInstanceIdleTtlMs(): number {
  const raw = process.env.OMNIRUSH_ENGINE_INSTANCE_IDLE_TTL_MS?.trim();
  if (!raw) return 15 * 60_000;
  const value = Number(raw);
  return Number.isFinite(value) && value >= 0 ? value : 15 * 60_000;
}

function sweepIntervalMs(): number {
  const value = Number(process.env.OMNIRUSH_ENGINE_INSTANCE_SWEEP_MS);
  return Number.isFinite(value) && value > 0 ? value : 60_000;
}

export class EngineInstanceReaper {
  private readonly hooks: EngineInstanceReaperHooks;
  private readonly instances = new Map<string, TrackedEngineInstance>();
  private readonly evictedWorkspaceIds = new Set<string>();
  private sweepTimer: ReturnType<typeof setInterval> | null = null;
  private sweeping = false;
  private closed = false;

  constructor(hooks: EngineInstanceReaperHooks) {
    this.hooks = hooks;
  }

  /**
   * Record traffic for a directory instance. Returns true exactly once after
   * that workspace's instance was evicted, so the caller can re-attach the
   * state a fresh instance cannot recover from disk.
   */
  noteUsed(use: EngineInstanceUse): boolean {
    if (this.closed) return false;
    const existing = this.instances.get(use.directory);
    if (existing && existing.engineBaseUrl === use.engineBaseUrl) {
      existing.workspaceId = use.workspaceId;
      existing.lastUsedAt = this.now();
    } else {
      // A different engine URL means a new engine process; streams held on the
      // previous generation were aborted with it.
      this.instances.set(use.directory, { ...use, lastUsedAt: this.now(), streamHolds: 0 });
    }
    return this.evictedWorkspaceIds.delete(use.workspaceId);
  }

  /**
   * Hold the instance while an engine event stream from its workspace stays
   * open, so a workspace that is visible anywhere in the UI is never evicted.
   * Unlike `noteUsed` this never consumes the one-shot post-eviction mark;
   * callers report that mark through their own `noteUsed` call.
   */
  holdStream(use: EngineInstanceUse): () => void {
    if (this.closed) return () => undefined;
    const existing = this.instances.get(use.directory);
    let entry: TrackedEngineInstance;
    if (existing && existing.engineBaseUrl === use.engineBaseUrl) {
      existing.workspaceId = use.workspaceId;
      existing.lastUsedAt = this.now();
      entry = existing;
    } else {
      entry = { ...use, lastUsedAt: this.now(), streamHolds: 0 };
      this.instances.set(use.directory, entry);
    }
    entry.streamHolds += 1;
    let released = false;
    return () => {
      if (released) return;
      released = true;
      const current = this.instances.get(use.directory);
      if (!current || current.engineBaseUrl !== use.engineBaseUrl) return;
      current.streamHolds = Math.max(0, current.streamHolds - 1);
      current.lastUsedAt = this.now();
    };
  }

  snapshot(): TrackedEngineInstance[] {
    return [...this.instances.values()].map((entry) => ({ ...entry }));
  }

  start(): void {
    if (this.closed || this.sweepTimer) return;
    const timer = setInterval(() => void this.sweep().catch(() => undefined), sweepIntervalMs());
    timer.unref?.();
    this.sweepTimer = timer;
  }

  close(): void {
    this.closed = true;
    if (this.sweepTimer) {
      clearInterval(this.sweepTimer);
      this.sweepTimer = null;
    }
    this.instances.clear();
    this.evictedWorkspaceIds.clear();
  }

  /** Run one eviction pass. Returns how many instances were evicted. */
  async sweep(): Promise<number> {
    if (this.closed || this.sweeping) return 0;
    const ttl = engineInstanceIdleTtlMs();
    if (ttl <= 0) return 0;
    const engineBaseUrl = this.hooks.engineBaseUrl();
    if (!engineBaseUrl) return 0;
    this.sweeping = true;
    try {
      const activeDirectory = this.hooks.activeDirectory();
      let evicted = 0;
      for (const entry of [...this.instances.values()]) {
        if (this.closed) break;
        if (entry.engineBaseUrl !== engineBaseUrl) {
          // The engine process this instance lived in is gone; there is
          // nothing left to dispose.
          this.instances.delete(entry.directory);
          continue;
        }
        if (entry.directory === activeDirectory) {
          entry.lastUsedAt = this.now();
          continue;
        }
        if (entry.streamHolds > 0) continue;
        if (this.now() - entry.lastUsedAt < ttl) continue;
        let busy: boolean;
        try {
          busy = await this.hooks.directoryBusy(entry);
        } catch (error) {
          this.hooks.logger?.log("warn", "Engine instance activity probe failed; the instance stays.", {
            "engine.instance.directory": entry.directory,
            "engine.instance.workspace_id": entry.workspaceId,
            "error.message": error instanceof Error ? error.message : String(error),
          });
          continue;
        }
        if (busy) {
          entry.lastUsedAt = this.now();
          continue;
        }
        // Traffic may have landed while the probe ran; a fresh touch wins.
        if (this.now() - entry.lastUsedAt < ttl) continue;
        try {
          await this.hooks.dispose(entry);
        } catch (error) {
          this.hooks.logger?.log("warn", "Idle engine instance dispose failed; it will be retried.", {
            "engine.instance.directory": entry.directory,
            "engine.instance.workspace_id": entry.workspaceId,
            "error.message": error instanceof Error ? error.message : String(error),
          });
          continue;
        }
        this.instances.delete(entry.directory);
        this.evictedWorkspaceIds.add(entry.workspaceId);
        evicted += 1;
        this.hooks.logger?.log("info", "Evicted an idle engine instance.", {
          "engine.instance.directory": entry.directory,
          "engine.instance.workspace_id": entry.workspaceId,
          "engine.instance.idle_ms": this.now() - entry.lastUsedAt,
        });
      }
      return evicted;
    } finally {
      this.sweeping = false;
    }
  }

  private now(): number {
    return this.hooks.now?.() ?? Date.now();
  }
}

const reaperByConfig = new WeakMap<ServerConfig, EngineInstanceReaper>();

export function setEngineInstanceReaperForConfig(config: ServerConfig, reaper: EngineInstanceReaper): void {
  reaperByConfig.set(config, reaper);
}

export function engineInstanceReaperForConfig(config: ServerConfig): EngineInstanceReaper | null {
  return reaperByConfig.get(config) ?? null;
}

export function clearEngineInstanceReaperForConfig(config: ServerConfig): void {
  reaperByConfig.delete(config);
}