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.

7.9 KB
Raw Blame
import { fileURLToPath } from "node:url";

import {
  WorkerDocumentNormalizer,
  type DocumentNormalizer,
} from "./document-normalizer/document-normalizer.js";
import { createJsonLogger, type JsonLogger } from "@linger/service-kit/node";

import type { Flashback } from "./flashback.js";
import type { ModelCall } from "./runtime-model-call.js";
import { startHttpHost, type HttpHost } from "./http-host.js";
import { pruneModelPackages } from "./model-packages.js";
import {
  NODE_SERVICES_DEFAULT_ADDRESS,
  readListenAddress,
  type ListenAddress,
} from "./listen-address.js";
import {
  SHUTDOWN_TIMEOUT_MS,
  runServiceProcess,
  type ProcessControl,
} from "./process-lifecycle.js";

interface RunningRole {
  /** Called once every selected role has started, for background work that
   * uses a seam a later role fills, such as the agent role's model call. */
  started?(): void;
  /** Called on every role before the first role stops, so that background
   * work stops taking new items while the roles it calls drain. */
  stopping?(): void;
  stop(): Promise<void>;
}

/** What the host passes to every role's start function. */
interface RoleHost extends ProcessControl {
  readonly logger: JsonLogger;
  /** The shared listener; present whenever an HTTP role is selected. */
  readonly http: HttpHost | undefined;
  /** The process's one document normalizer, served by LLM Wiki. */
  readonly normalizer: DocumentNormalizer;
  /** What a role hands to the roles that start after it. The agent role fills
   * modelCall after Memory and LLM Wiki have started, so they read it when
   * they call, and Memory's scheduler starts only from started(). */
  readonly seams: { flashback?: Flashback; modelCall?: ModelCall };
  /** Replaces the Agent Service's Room request timeout in process tests. */
  readonly agentRoomRequestTimeoutMs?: number;
}

// Each role loads only when selected, so a single-role process skips the
// other roles' dependencies. Roles start in this order and stop in reverse:
// the Agent Service stops before the Memory it calls, and the Document
// Runtime, which starts last, drains first.
const roles = {
  memory: async (host: RoleHost) => {
    const memory = await (
      await import("./memory/main.js")
    ).startMemoryService({
      http: requireHttp(host),
      logger: host.logger,
      modelCall: () => host.seams.modelCall,
    });
    host.seams.flashback = memory.flashback;
    return memory;
  },
  "llm-wiki": async (host: RoleHost) =>
    (await import("./llm-wiki/service.js")).startLlmWikiService({
      http: requireHttp(host),
      logger: host.logger,
      normalizer: host.normalizer,
      modelCall: () => host.seams.modelCall,
    }),
  agent: async (host: RoleHost) => {
    const http = requireHttp(host);
    const agent = await (
      await import("./agent/main.js")
    ).startAgentService({
      ...host,
      http,
      ...(host.seams.flashback ? { flashback: host.seams.flashback } : {}),
      ...(host.agentRoomRequestTimeoutMs
        ? { roomRequestTimeoutMs: host.agentRoomRequestTimeoutMs }
        : {}),
    });
    host.seams.modelCall = agent.modelCall;
    return {
      stop: async () => {
        host.seams.modelCall = undefined;
        await agent.stop();
      },
    };
  },
  voice: async (host: RoleHost) =>
    (await import("./voice/service.js")).startVoiceService({
      logger: host.logger,
      http: requireHttp(host),
    }),
  // The Document Runtime keeps its own port on its own worker thread and logs
  // from that thread; the host logger only records the thread's restarts.
  document: async (host: RoleHost) =>
    (await import("./document/main.js")).startDocumentService({
      logger: host.logger,
    }),
} satisfies Record<string, (host: RoleHost) => Promise<RunningRole>>;

type RoleName = keyof typeof roles;

/** Roles that serve requests on the shared HTTP listener. */
const HTTP_ROLES: ReadonlySet<RoleName> = new Set([
  "memory",
  "llm-wiki",
  "agent",
  "voice",
]);

/** An unset or empty NODE_SERVICES_ROLES starts every role. */
export function selectRoles(value: string | undefined): RoleName[] {
  const names = (value ?? "")
    .split(",")
    .map((name) => name.trim())
    .filter(Boolean);
  const all = Object.keys(roles) as RoleName[];
  if (names.length === 0) return all;
  const unknown = names.filter((name) => !Object.hasOwn(roles, name));
  if (unknown.length > 0) {
    throw new Error(
      `NODE_SERVICES_ROLES contains unknown roles: ${unknown.join(", ")}; ` +
        `expected ${all.join(", ")}`,
    );
  }
  // Selected roles keep the host's start order.
  return all.filter((name) => names.includes(name));
}

/** The shared listener's address from NODE_SERVICES_HTTP_ADDRESS. */
export function readHttpAddress(environment: NodeJS.ProcessEnv): ListenAddress {
  // Tests bind an ephemeral port; a deployment always names its port.
  return readListenAddress(
    environment,
    "NODE_SERVICES_HTTP_ADDRESS",
    NODE_SERVICES_DEFAULT_ADDRESS,
    environment.NODE_ENV === "test",
  );
}

function requireHttp(host: RoleHost): HttpHost {
  if (!host.http) throw new Error("The shared HTTP listener is not running");
  return host.http;
}

/** Runs the selected roles; process tests start it with shorter timeouts. */
export async function main(
  overrides: { agentRoomRequestTimeoutMs?: number } = {},
): Promise<void> {
  const logger = createJsonLogger({ service: "node-services" });
  await runServiceProcess(async (control) => {
    const selected = selectRoles(process.env.NODE_SERVICES_ROLES);
    const http = selected.some((name) => HTTP_ROLES.has(name))
      ? await startHttpHost(readHttpAddress(process.env))
      : undefined;
    const normalizer = new WorkerDocumentNormalizer();
    void pruneModelPackages().then(
      (removed) => {
        if (removed.length)
          logger.log("info", "model_packages.pruned", { packages: removed });
      },
      (error: unknown) =>
        logger.log("warn", "model_packages.prune_failed", { error }),
    );
    const seams: RoleHost["seams"] = {};
    const running: { name: RoleName; role: RunningRole }[] = [];
    const stopRoles = async (): Promise<void> => {
      const failures: unknown[] = [];
      const stopping = running.splice(0).reverse();
      for (const { role } of stopping) role.stopping?.();
      const voice = stopping.find(({ name }) => name === "voice");
      const voiceStopped = voice?.role.stop().catch((error) => {
        failures.push(error);
      });
      for (const { name, role } of stopping.filter(
        ({ name }) => name !== "voice",
      )) {
        control.progress(`role:${name}`, "started");
        try {
          await role.stop();
          control.progress(`role:${name}`, "completed");
        } catch (error) {
          control.progress(`role:${name}`, "failed");
          logger.log("error", "host.role_stop_failed", { error, role: name });
          failures.push(error);
        }
      }
      await voiceStopped;
      control.progress("http", "started");
      await http?.close();
      control.progress("http", "completed");
      if (failures.length > 0) {
        throw new AggregateError(
          failures,
          "Node Services roles failed to stop",
        );
      }
    };
    try {
      for (const name of selected) {
        control.signal.throwIfAborted();
        const role = await roles[name]({
          ...control,
          http,
          logger: logger.child({ role: name }),
          normalizer,
          seams,
          ...overrides,
        });
        running.push({ name, role });
      }
      for (const { role } of running) role.started?.();
      http?.finishStartup();
      if (http) logger.log("info", "host.listening", { url: http.url });
    } catch (error) {
      await stopRoles().catch((stopError: unknown) => {
        logger.log("error", "host.start_cleanup_failed", { error: stopError });
      });
      throw error;
    }
    return { close: stopRoles };
  }, SHUTDOWN_TIMEOUT_MS);
}

if (process.argv[1] === fileURLToPath(import.meta.url)) {
  void main();
}