Skip to content

A desktop coding agent with free access to frontier models.

TypeScript
18.3 KB
Raw Blame
/**
 * Single entry point for embedding the OmniRush.ai server in-process.
 *
 * Handles config resolution, managed OpenCode spawn, and server start
 * in one call -- mirrors what cli.ts does but returns a handle instead
 * of owning the process lifecycle.
 */
import { agentAssistEngineEnv, agentAssistFlags } from "./agent-assist-config.js";
import { readGlobalRuntimeOpencodeConfig } from "./runtime-opencode-config-store.js";
import { randomUUID } from "node:crypto";
import { stopTaskRecovery } from "./task-recovery.js";
import { managedDesktopPolicy } from "./managed-desktop-policy.js";
import { mkdir } from "node:fs/promises";
import { engineToolsRoot, setToolsRoot } from "./box/box.js";
import { setWriteCheckEngine } from "./folder-write-check.js";
import { applyStockSwitches } from "./stock-mode/stock-mode.mjs";
import { resolveServerConfig, type CliArgs } from "./config.js";
import {
  buildEngineAuthProbeHeader,
  registerEngineInstance,
  removeEngineInstance,
  reapOrphanEngineInstances,
} from "./engine-registry.js";
import {
  clearEnginePoolForConfig,
  computeEngineConfigFingerprint,
  type EnginePool,
  type EnginePoolSnapshot,
  type EngineSpawnTemplate,
} from "./engine-pool.js";
import { createManagedOpencodeServer, pluginsNoDepsEnv, type ManagedOpencodeServer, type OpencodeExecutionSnapshot } from "./managed-opencode.js";
import {
  clearTrustedOpencodeProcess,
  collectBusyEngineSessions,
  createEnginePoolForConfig,
  stopTurnActivity,
  createServerLogger,
  registerTrustedOpencodeProcess,
  startServer,
  syncAllWorkspacesRuntimeMcpToEngine,
} from "./server.js";
import { ensureLocalWorkspaceFiles } from "./workspace-init.js";
import { findManagedEngineWorkspace } from "./workspaces.js";
import { keepOmniRushRuntimeConfigFileFresh, omnirushOwnPluginPaths, writeOmniRushRuntimeConfigFile } from "./omnirush-runtime-config.js";
import { migrateOmniRushCloudMcpRuntimeConfig } from "./cloud-mcp-health.js";
import { migrateWorkspaceRuntimeConfigToEngineGlobal } from "./runtime-opencode-config-store.js";
import { migrateLegacyOmniRushUiMcpCommand, type OmniRushUiMcpLaunch } from "./omnirush-ui-mcp-migration.js";
import { resolveOpencodeModelsEnv } from "./opencode-models-url.js";
import { assertOpencodeConfigCompat } from "./opencode-config-compat.js";
import { adoptOpencodeCredentials, startEngine2SessionImport } from "./engine2/import.js";
import type { ServeResult } from "./serve-node.js";
import type { CaptureFileUpload, LocalManagedMcpVaultKeyProvider, OmniRushGatewayCredentials, ServerConfig } from "./types.js";
import { mcpEngineEnv } from "./mcp-allow/state.js";
import { runtimeStorageDir } from "./runtime-db.js";

export type EmbeddedServerOptions = CliArgs & {
  /** When true, spawn a managed OpenCode child process. */
  manageOpencode?: boolean;
  /** Path to the OpenCode binary. Falls back to OMNIRUSH_OPENCODE_BIN env. */
  opencodeBin?: string;
  /** Working directory for the managed OpenCode process. */
  opencodeCwd?: string;
  /** Secure key custody for the local managed MCP credential vault. */
  localManagedMcpVaultKey?: LocalManagedMcpVaultKeyProvider;
  /** Account credentials held by the Desktop shell for the loopback gateway broker. */
  omnirushGatewayCredentials?: OmniRushGatewayCredentials;
  resumeInterruptedTasks?: boolean;
  /** Version of the embedding desktop app, reported as environment.app_version by the session uploader. */
  appVersion?: string;
  /** File-aware transport for immutable compressed session uploads. */
  captureFileUpload?: CaptureFileUpload;
  /** The user signed out since the last start: queued uploads and archives are deleted first. */
  clearUploadQueue?: boolean;
  /** Called when the agent starts working (a prompt went out) and when no turn runs any more. */
  onTurnActivity?: (running: boolean) => void;
  /**
   * How the embedding desktop launches its bundled UI-control MCP. Persisted
   * entries still using `npx -y omnirush-ui-mcp` are rewritten to it before
   * the engine starts; without it they are removed instead.
   */
  omnirushUiMcp?: OmniRushUiMcpLaunch | null;
};

export type EmbeddedServerHandle = {
  /** Bound port the HTTP server is listening on. */
  port: number;
  /** Full base URL, e.g. http://127.0.0.1:48123 */
  url: string;
  /** The resolved server config (with OpenCode URLs populated). */
  config: ServerConfig;
  /** Redacted details for the managed OpenCode child process, when spawned. */
  managedOpencodeExecution: OpencodeExecutionSnapshot | null;
  /** Liveness for the managed OpenCode child process, when spawned. */
  managedOpencode: { pid: number | null; isAlive: () => boolean } | null;
  /** Current managed-engine generations for desktop diagnostics and acceptance checks. */
  managedOpencodePool: () => EnginePoolSnapshot | null;
  /**
   * Sessions still running on the managed engine. The desktop asks before any
   * unattended restart; `unknown` counts unreadable probes, which it treats as busy.
   */
  busySessions: () => Promise<{ sessions: string[]; unknown: number }>;
  /** Stop the HTTP server and managed OpenCode (if any). */
  stop: () => Promise<void>;
};

export async function startEmbeddedServer(options: EmbeddedServerOptions): Promise<EmbeddedServerHandle> {
  // Stock mode (OMNIRUSH_FARM at launch): its switches for the whole app process, before anything reads them.
  applyStockSwitches(process.env);
  const config = await resolveServerConfig(options);
  config.localManagedMcpVaultKey = options.localManagedMcpVaultKey;
  config.omnirushGatewayCredentials = options.omnirushGatewayCredentials;
  config.omnirushEngineToken = randomUUID();
  // Interrupted tasks resume on the app's own engines (the 2.x one runs whether or not a 1.x engine is managed).
  config.resumeInterruptedTasks = options.resumeInterruptedTasks === true && !config.opencodeBaseUrl;
  config.appVersion = typeof options.appVersion === "string" && options.appVersion.trim() ? options.appVersion.trim() : undefined;
  config.captureFileUpload = options.captureFileUpload;
  config.clearUploadQueue = options.clearUploadQueue === true;
  config.onTurnActivity = options.onTurnActivity;
  const logger = createServerLogger(config);

  // Spawn managed OpenCode if requested and no explicit base URL was provided.
  let managedOpencode: ManagedOpencodeServer | null = null;
  let managedOpencodeIdentity: string | null = null;
  let managedEngineRecordId: string | null = null;
  let engineSpawnTemplate: EngineSpawnTemplate | null = null;
  let enginePool: EnginePool | null = null;
  let stopRuntimeConfigFileRefresh: (() => void) | null = null;
  let server: ServeResult | null = null;
  let stopPromise: Promise<void> | null = null;

  const releaseResources = async (): Promise<void> => {
    const errors: unknown[] = [];
    stopTurnActivity(config);
    try { await stopTaskRecovery(config); } catch (error) { errors.push(error); }

    const identity = managedOpencodeIdentity;
    managedOpencodeIdentity = null;
    if (identity && !enginePool) {
      try {
        clearTrustedOpencodeProcess(config, identity);
      } catch (error) {
        errors.push(error);
      }
    }

    // With rollover enabled the pool owns every engine process, including any
    // still draining, so it is the one that must close them.
    const pool = enginePool;
    enginePool = null;
    if (pool) {
      clearEnginePoolForConfig(config);
      try {
        await pool.disposeAll();
      } catch (error) {
        errors.push(error);
      }
    }

    const opencode = managedOpencode;
    managedOpencode = null;
    if (opencode && !pool) {
      try {
        await opencode.close();
      } catch (error) {
        errors.push(error);
      }
    }

    const engineRecordId = managedEngineRecordId;
    managedEngineRecordId = null;
    if (engineRecordId) {
      await removeEngineInstance(config, engineRecordId).catch(() => undefined);
    }

    const httpServer = server;
    server = null;
    if (httpServer) {
      try {
        await httpServer.stop();
      } catch (error) {
        errors.push(error);
      }
    }

    const unsubscribe = stopRuntimeConfigFileRefresh;
    stopRuntimeConfigFileRefresh = null;
    if (unsubscribe) {
      try {
        unsubscribe();
      } catch (error) {
        errors.push(error);
      }
    }

    if (errors.length === 1) throw errors[0];
    if (errors.length > 1) {
      throw new AggregateError(errors, "Failed to stop embedded OmniRush.ai server");
    }
  };

  const stop = (): Promise<void> => {
    stopPromise ??= releaseResources();
    return stopPromise;
  };

  const duringStartup = async <T>(operation: () => Promise<T>): Promise<T> => {
    try {
      return await operation();
    } catch (startupError) {
      try {
        await stop();
      } catch (cleanupError) {
        throw new AggregateError(
          [startupError, cleanupError],
          "Embedded OmniRush.ai server startup failed and cleanup was incomplete",
        );
      }
      throw startupError;
    }
  };

  if (!config.readOnly) {
    // The desktop creates a workspace's folder when it adds the workspace; a
    // registered workspace whose folder is gone is never recreated at startup.
    await ensureLocalWorkspaceFiles(config.workspaces, { createMissing: false });
    // First among the runtime-DB migrations: the store drops leftover
    // registry launches on any write, before this could rewrite them.
    await migrateLegacyOmniRushUiMcpCommand(config, options.omnirushUiMcp ?? null);
    await migrateOmniRushCloudMcpRuntimeConfig(config);
    await migrateWorkspaceRuntimeConfigToEngineGlobal(config);
  }

  // Bind the HTTP server before spawning the engine: serve-node may fall back
  // to an OS-assigned port on EADDRINUSE, and the engine's spawn-time env
  // (OMNIRUSH_SERVER_URL) must point at the port that actually bound, not the
  // requested one. Proxy requests that land in the short window before the
  // engine is ready fail with opencode_unconfigured and clients retry; the
  // desktop only learns the server URL after this function returns.
  // The Linux sandbox's helpers ship beside the engine (sidecars/box/): known before the server plans any box.
  const engineBin = options.opencodeBin || process.env.OMNIRUSH_OPENCODE_BIN;
  // The 2.x engine ships in the same sidecars folder: an app without the 1.x engine finds the helpers there.
  setToolsRoot(engineToolsRoot(options.opencodeBin));
  setWriteCheckEngine(engineBin);
  server = await duringStartup(() => startServer(config));
  config.port = server.port;
  const serverUrl = `http://${config.host === "0.0.0.0" ? "127.0.0.1" : config.host}:${server.port}`;
  delete process.env.OMNIRUSH_ENGINE_GATEWAY_URL;
  delete process.env.OMNIRUSH_ACCESS_TOKEN;
  delete process.env.OMNIRUSH_REFRESH_TOKEN;
  if (config.omnirushGatewayCredentials && config.omnirushEngineToken) {
    process.env.OMNIRUSH_ENGINE_GATEWAY_URL = `${serverUrl}/omnirush-gateway/v1`;
    process.env.OMNIRUSH_ACCESS_TOKEN = config.omnirushEngineToken;
  }

  if (!config.opencodeBaseUrl && options.manageOpencode) {
    const workspace = findManagedEngineWorkspace(config.workspaces);
    if (workspace) {
      // Reap engines recorded by servers that died without cleanup. Best
      // effort: a failed reap must never block startup.
      await reapOrphanEngineInstances(config).catch(() => undefined);
      // Server-managed config file: the engine re-reads it from disk on every
      // instance rebuild, and keepOmniRushRuntimeConfigFileFresh synchronizes it
      // on every runtime-DB write — so disposes always pick up current state.
      const { path: runtimeConfigPath } = await writeOmniRushRuntimeConfigFile(config);
      stopRuntimeConfigFileRefresh = keepOmniRushRuntimeConfigFileFresh(config);
      const cwd = options.opencodeCwd
        || process.env.OMNIRUSH_MANAGED_OPENCODE_CWD?.trim()
        || workspace.path;
      await duringStartup(() => mkdir(cwd, { recursive: true }));
      const opencodeModelsEnv = await duringStartup(() => resolveOpencodeModelsEnv());

      const opencodeBin = options.opencodeBin || process.env.OMNIRUSH_OPENCODE_BIN;
      // Shared by the first spawn and by any later rollover standby, so a
      // replacement engine is identical apart from its port.
      const engineEnv: Record<string, string | undefined> = {
        ...(process.env.OMNIRUSH_DEV_MODE ? { OMNIRUSH_DEV_MODE: process.env.OMNIRUSH_DEV_MODE } : {}),
        ...(process.env.OMNIRUSH_UI_CONTROL_DISCOVERY ? { OMNIRUSH_UI_CONTROL_DISCOVERY: process.env.OMNIRUSH_UI_CONTROL_DISCOVERY } : {}),
        ...(config.omnirushGatewayCredentials && config.omnirushEngineToken
          ? { OMNIRUSH_ACCESS_TOKEN: config.omnirushEngineToken }
          : {}),
        OMNIRUSH_SERVER_URL: serverUrl,
        OMNIRUSH_SERVER_TOKEN: config.token,
        OMNIRUSH_POLICY_TOKEN: managedDesktopPolicy(config).evaluationToken,
        OPENCODE_CONFIG: runtimeConfigPath,
        ...opencodeModelsEnv,
        // The MCP plugin's policy, report and app-added servers (mcp-allow/state.ts).
        ...mcpEngineEnv(runtimeStorageDir(config)),
        ...pluginsNoDepsEnv(omnirushOwnPluginPaths()),
        // Agent assist: the plugin's switch file and notes folder, the language servers' heap cap.
        ...agentAssistEngineEnv(config, process.env, { diagnostics: agentAssistFlags(await readGlobalRuntimeOpencodeConfig(config)).diagnostics }),
      };
      engineSpawnTemplate = {
        bin: opencodeBin,
        cwd,
        runtimeConfigPath,
        env: engineEnv,
        reservedPorts: () => {
          const poolPorts = enginePool?.connections()
            .map((connection) => Number(new URL(connection.baseUrl).port) || 0)
            .filter((port) => port > 0) ?? [];
          const startupPort = managedOpencode ? Number(new URL(managedOpencode.url).port) || 0 : 0;
          return [...new Set([config.port, ...poolPorts, startupPort].filter((port) => port > 0))];
        },
      };
      // The bundled engine (1.18.32+) refuses user-owned config files that
      // carry a V2 `permissions` key: a global file exits the engine at boot,
      // a workspace file breaks that workspace's instance. Name the file and
      // the keys here, before the spawn, instead of surfacing an opaque exit.
      await duringStartup(() => assertOpencodeConfigCompat({
        workspaceRoots: config.workspaces
          .filter((entry) => entry.workspaceType !== "remote")
          .map((entry) => entry.path),
        env: { ...process.env, ...engineEnv },
        logger,
      }));
      adoptOpencodeCredentials({ ...process.env, ...engineEnv }, (level, message, attributes) => logger.log(level, message, attributes));
      managedOpencode = await duringStartup(() => createManagedOpencodeServer({
        bin: opencodeBin,
        cwd,
        excludedPorts: [config.port],
        env: engineEnv,
      }));
      // Sessions the 2.x engine of OmniRush.ai 2.2.0 – 3.x stored: copied once into this engine's store.
      void startEngine2SessionImport({
        bin: opencodeBin?.trim() || "opencode",
        env: { ...process.env, ...engineEnv },
        log: (level, message, attributes) => logger.log(level, message, attributes),
      });

      config.opencodeBaseUrl = managedOpencode.url;
      config.opencodeUsername = managedOpencode.username;
      config.opencodePassword = managedOpencode.password;
      for (const entry of config.workspaces) {
        if (entry.workspaceType === "remote") {
          entry.baseUrl ??= managedOpencode.url;
          entry.opencodeUsername ??= managedOpencode.username;
          entry.opencodePassword ??= managedOpencode.password;
          entry.directory ??= entry.path;
          continue;
        }
        entry.baseUrl = managedOpencode.url;
        entry.opencodeUsername = managedOpencode.username;
        entry.opencodePassword = managedOpencode.password;
        entry.directory = entry.path;
      }
      // The identity only needs to be unique per managed-process boot; a
      // random nonce provides that without routing the engine credentials
      // through the fast identity hash.
      managedOpencodeIdentity = [
        managedOpencode.pid ?? "unknown",
        randomUUID(),
      ].join(":");
      registerTrustedOpencodeProcess(config, {
        baseUrl: managedOpencode.url,
        identity: managedOpencodeIdentity,
        isAlive: managedOpencode.isAlive,
      });
      if (managedOpencode.pid) {
        managedEngineRecordId = randomUUID();
        await registerEngineInstance(config, {
          id: managedEngineRecordId,
          pid: managedOpencode.pid,
          port: Number(new URL(managedOpencode.url).port) || 0,
          url: managedOpencode.url,
          startedAt: Date.now(),
          role: "primary",
          serverRunId: managedOpencodeIdentity,
          ownerPid: process.pid,
          authProbe: buildEngineAuthProbeHeader(managedOpencode.username, managedOpencode.password),
          bin: opencodeBin?.trim() || "opencode",
        }).catch(() => undefined);
      }
    }
  }

  // The runtime config file above only covers workspaces[0]. Push every
  // workspace's runtime-DB MCPs into the engine so they aren't invisible
  // until a manual reload. Best-effort.
  if (managedOpencode) {
    void syncAllWorkspacesRuntimeMcpToEngine(config).catch((error) => {
      logger.log("error", "Startup MCP synchronization crashed.", {
        "mcp.trigger": "startup",
        "mcp.failure.message": error instanceof Error ? error.message : String(error),
      });
    });
  }

  if (managedOpencode && engineSpawnTemplate) {
    enginePool = createEnginePoolForConfig({
      config,
      template: engineSpawnTemplate,
      handle: managedOpencode,
      fingerprint: await computeEngineConfigFingerprint(engineSpawnTemplate),
      registryId: managedEngineRecordId,
      trustedIdentity: managedOpencodeIdentity,
    });
  }

  const initialManagedOpencode = managedOpencode;
  return {
    port: server.port,
    url: `http://${config.host === "0.0.0.0" ? "127.0.0.1" : config.host}:${server.port}`,
    config,
    managedOpencodeExecution: managedOpencode?.execution ?? null,
    managedOpencode: initialManagedOpencode
      ? {
          get pid() {
            return enginePool?.primaryProcess()?.pid ?? initialManagedOpencode.pid ?? null;
          },
          isAlive: () => enginePool?.primaryProcess()?.isAlive() ?? initialManagedOpencode.isAlive(),
        }
      : null,
    managedOpencodePool: () => enginePool?.snapshot() ?? null,
    busySessions: () => collectBusyEngineSessions(config),
    stop,
  };
}