Skip to content

Linger is An Open-Source Personal Agent That Runs Fully on Your PC. We aim to break Big Tech’s grip on AI by bringing powerful local AI to everyday computers through efficient model–harness co-design, so everyone can run their own.

6.9 KB
Raw Blame
import { spawn, type ChildProcess } from "node:child_process";
import { fileURLToPath } from "node:url";
import path from "node:path";

const packageRoot = fileURLToPath(new URL("../", import.meta.url));
const hostEntryPoint = path.join(packageRoot, "src/main.ts");
const featureCatalogGenerator = path.join(
  packageRoot,
  "scripts/generate-feature-catalog.ts",
);

type NodeServicesChild = Pick<ChildProcess, "kill" | "off" | "once">;

/**
 * `pnpm dev` runs Node Services through this supervisor: it waits for TeamHub,
 * which the Agent Service needs at startup, and restarts the process after a
 * crash instead of letting `concurrently` stop the whole stack. It does not
 * watch files, so an edit never interrupts a running Wiki generation.
 */
export interface NodeServicesDevSupervisorOptions {
  signal: AbortSignal;
  spawnNodeServices?: () => NodeServicesChild;
  waitForTeamHub?: (signal: AbortSignal) => Promise<void>;
  waitBeforeRestart?: (signal: AbortSignal) => Promise<void>;
  /**
   * Regenerates the static agent-features manifest before each (re)start so
   * restarts after adding or removing a feature directory always spawn the
   * Agent Service against the current catalog.
   */
  refreshFeatureCatalog?: (signal: AbortSignal) => Promise<void>;
}

export async function superviseNodeServicesDevelopment(
  options: NodeServicesDevSupervisorOptions,
): Promise<void> {
  const spawnNodeServices =
    options.spawnNodeServices ?? defaultSpawnNodeServices;
  const waitForTeamHub =
    options.waitForTeamHub ??
    ((signal) => waitForTeamHubHealth(readTeamHubHealthUrl(), signal));
  const waitBeforeRestart =
    options.waitBeforeRestart ?? ((signal) => delay(500, signal));
  const refreshFeatureCatalog =
    options.refreshFeatureCatalog ?? generateFeatureCatalog;

  while (!options.signal.aborted) {
    await waitForTeamHub(options.signal);
    if (options.signal.aborted) return;

    await refreshFeatureCatalog(options.signal);
    if (options.signal.aborted) return;

    const result = await waitForChildExit(spawnNodeServices(), options.signal);
    if (options.signal.aborted) return;

    const reason = result.error
      ? result.error.message
      : `exit code ${String(result.code)}${result.signal ? ` (${result.signal})` : ""}`;
    console.error(
      `[node-services] Node Services stopped with ${reason}; restarting.`,
    );
    await waitBeforeRestart(options.signal);
  }
}

export async function waitForTeamHubHealth(
  healthUrl: string,
  signal: AbortSignal,
  options: {
    fetcher?: typeof fetch;
    retryDelayMs?: number;
    requestTimeoutMs?: number;
    sleep?: (milliseconds: number, signal: AbortSignal) => Promise<void>;
  } = {},
): Promise<void> {
  const fetcher = options.fetcher ?? fetch;
  const retryDelayMs = options.retryDelayMs ?? 500;
  const requestTimeoutMs = options.requestTimeoutMs ?? 1_000;
  const sleep = options.sleep ?? delay;

  while (!signal.aborted) {
    try {
      const response = await fetcher(healthUrl, {
        signal: AbortSignal.any([
          signal,
          AbortSignal.timeout(requestTimeoutMs),
        ]),
      });
      if (response.ok) return;
    } catch {
      // TeamHub is still starting or reloading.
    }

    await sleep(retryDelayMs, signal);
  }
}

function defaultSpawnNodeServices(): NodeServicesChild {
  return spawn(process.execPath, ["--import", "tsx", hostEntryPoint], {
    cwd: packageRoot,
    stdio: "inherit",
  });
}

// Runs as its own process, like Node Services, so this supervisor keeps only
// built-in imports. Its notes go to stderr; stdout belongs to Node Services.
// The desktop's offline runtime ships main.ts compiled beside this file, with
// its feature catalog built in (apps/desktop/scripts/build-native-runtime.mjs).
// It stays in this process's directory, the checkout, against which the
// bundle resolves relative settings.
function spawnCompiledNodeServices(): NodeServicesChild {
  return spawn(
    process.execPath,
    ["--conditions=linger-production", path.join(packageRoot, "dist/main.js")],
    { stdio: "inherit", windowsHide: true },
  );
}

async function generateFeatureCatalog(signal: AbortSignal): Promise<void> {
  const result = await waitForChildExit(
    spawn(process.execPath, ["--import", "tsx", featureCatalogGenerator], {
      cwd: packageRoot,
      stdio: ["ignore", 2, 2],
    }),
    signal,
  );
  if (signal.aborted) return;
  if (result.error) throw result.error;
  if (result.code !== 0) {
    throw new Error(
      `agent-features catalog generation exited with code ${String(result.code)}`,
    );
  }
}

function readTeamHubHealthUrl(): string {
  // Same single-host default as the Agent Service itself; tests run this
  // script without the service sources beside it.
  const baseUrl =
    process.env.TEAMHUB_BASE_URL?.trim() || "http://127.0.0.1:8080";
  return new URL("healthz", `${baseUrl.replace(/\/$/, "")}/`).toString();
}

function waitForChildExit(
  child: NodeServicesChild,
  signal: AbortSignal,
): Promise<{
  code: number | null;
  error?: Error;
  signal: NodeJS.Signals | null;
}> {
  return new Promise((resolve) => {
    const finish = (result: {
      code: number | null;
      error?: Error;
      signal: NodeJS.Signals | null;
    }): void => {
      child.off("error", onError);
      child.off("exit", onExit);
      signal.removeEventListener("abort", onAbort);
      resolve(result);
    };
    const onError = (error: Error): void => {
      finish({ code: null, error, signal: null });
    };
    const onExit = (
      code: number | null,
      exitSignal: NodeJS.Signals | null,
    ): void => {
      finish({ code, signal: exitSignal });
    };
    const onAbort = (): void => {
      child.kill("SIGTERM");
    };

    child.once("error", onError);
    child.once("exit", onExit);
    signal.addEventListener("abort", onAbort, { once: true });
    if (signal.aborted) onAbort();
  });
}

function delay(milliseconds: number, signal: AbortSignal): Promise<void> {
  if (signal.aborted) return Promise.resolve();

  return new Promise((resolve) => {
    const timer = setTimeout(finish, milliseconds);
    const onAbort = (): void => finish();

    function finish(): void {
      clearTimeout(timer);
      signal.removeEventListener("abort", onAbort);
      resolve();
    }

    signal.addEventListener("abort", onAbort, { once: true });
  });
}

async function main(): Promise<void> {
  const controller = new AbortController();
  process.once("SIGINT", () => controller.abort());
  process.once("SIGTERM", () => controller.abort());
  await superviseNodeServicesDevelopment({
    signal: controller.signal,
    ...(process.argv.includes("--compiled") && {
      spawnNodeServices: spawnCompiledNodeServices,
      refreshFeatureCatalog: async () => {},
    }),
  });
}

if (path.resolve(process.argv[1] ?? "") === fileURLToPath(import.meta.url)) {
  main().catch((error: unknown) => {
    console.error(error instanceof Error ? error.message : String(error));
    process.exitCode = 1;
  });
}