Skip to content

#1 Persistent memory for AI coding agents based on real-world benchmarks

8.2 KB
Raw Blame
import { statSync } from "node:fs";
import { join } from "node:path";

export const DEFAULT_ENGINE_TIMEOUT_MS = 120_000;
export const DEFAULT_WORKER_TIMEOUT_MS = 300_000;
export const MAX_STARTUP_TIMEOUT_MS = 3_600_000;

export function startupTimeouts(env: NodeJS.ProcessEnv = process.env): {
  engineMs: number;
  workerMs: number;
  engineManagesWorker: boolean | undefined;
} {
  const parse = (key: string, fallback: number): number => {
    const raw = env[key];
    if (raw === undefined) return fallback;
    const value = Number(raw);
    if (!/^\d+$/.test(raw) || !Number.isSafeInteger(value) || value < 1 || value > MAX_STARTUP_TIMEOUT_MS) {
      throw new Error(`${key} must be an integer between 1 and ${MAX_STARTUP_TIMEOUT_MS} milliseconds.`);
    }
    return value;
  };
  const ownership = env.AGENTMEMORY_ENGINE_MANAGES_WORKER;
  if (ownership !== undefined && ownership !== "true" && ownership !== "false") {
    throw new Error("AGENTMEMORY_ENGINE_MANAGES_WORKER must be true or false.");
  }
  return {
    engineMs: parse("AGENTMEMORY_ENGINE_READY_TIMEOUT_MS", DEFAULT_ENGINE_TIMEOUT_MS),
    workerMs: parse("AGENTMEMORY_READY_TIMEOUT_MS", DEFAULT_WORKER_TIMEOUT_MS),
    engineManagesWorker: ownership === undefined ? undefined : ownership === "true",
  };
}

// Used only for unattached native engine state persisted by legacy installs;
// new installs use Worker Compose.
export function configStartsAgentmemoryWorker(raw: string, workerEntry: string, engineCwd?: string): boolean {
  const lines = raw.split(/\r?\n/);
  let workerIndent: number | undefined;
  let execIndent: number | undefined;
  for (const line of lines) {
    if (!line.trim() || line.trimStart().startsWith("#")) continue;
    const indent = line.length - line.trimStart().length;
    if (workerIndent !== undefined && indent <= workerIndent) {
      workerIndent = undefined;
      execIndent = undefined;
    }
    if (/^\s*-\s+name:\s*(?:iii-exec|"iii-exec"|'iii-exec')(?:\s+#.*)?\s*$/.test(line)) {
      workerIndent = indent;
      continue;
    }
    if (workerIndent === undefined) continue;
    if (execIndent !== undefined && indent <= execIndent) execIndent = undefined;
    if (/^\s*exec:\s*(?:#.*)?$/.test(line)) {
      execIndent = indent;
      continue;
    }
    if (execIndent === undefined) continue;
    const scalar = line.match(/^\s*-\s+(.+)$/)?.[1]?.trim();
    if (!scalar) continue;
    const quoted = scalar.match(/^(["'])(.*?)\1(?:\s+#.*)?$/);
    const command = quoted ? quoted[2]! : scalar;
    const tokens = command.match(/"[^"]*"|'[^']*'|[^\s]+/g)?.map((token) => token.replace(/^("|')(.*)\1$/, "$2").replaceAll("\\", "/"));
    if (!tokens) continue;
    const comment = tokens.findIndex((token) => token.startsWith("#"));
    if (comment !== -1) tokens.splice(comment);
    const runtime = tokens[0]?.split("/").at(-1);
    if (runtime !== "node" && runtime !== "node.exe" && runtime !== "tsx") continue;
    if (runtime !== "tsx") {
      while (tokens[1] && /^(?:--max[-_]old[-_]space[-_]size=\d+|--enable-source-maps|--no-warnings)$/.test(tokens[1])) tokens.splice(1, 1);
    }
    const entry = tokens.length === 2
      ? tokens[1]
      : tokens.length === 4 && tokens[1] === "--import" && tokens[2] === "tsx" ? tokens[3] : undefined;
    if (entry === workerEntry.replaceAll("\\", "/")) return true;
    if (entry === "dist/index.mjs" || entry === "./dist/index.mjs" || entry === "src/index.ts" || entry === "./src/index.ts") {
      if (engineCwd === undefined) return true;
      try {
        if (statSync(join(engineCwd, entry)).isFile()) return true;
      } catch {}
    }
  }
  return false;
}

export function startupTimeoutMessage(kind: "engine" | "worker", timeoutMs: number): string {
  const name = kind === "engine" ? "iii-engine" : "agentmemory worker";
  const variable = kind === "engine" ? "AGENTMEMORY_ENGINE_READY_TIMEOUT_MS" : "AGENTMEMORY_READY_TIMEOUT_MS";
  return `${name} did not become ready within ${timeoutMs / 1000}s. Set ${variable} to allow more startup time.`;
}

export interface StartupDeadline {
  remaining(): number;
}

export function startupDeadline(timeoutMs: number): StartupDeadline {
  const deadline = performance.now() + timeoutMs;
  return { remaining: () => Math.max(0, deadline - performance.now()) };
}

/** Probe the loopback REST listener owned by this managed Compose instance.
 * Client commands may honor AGENTMEMORY_URL, but startup readiness must always
 * target the endpoint that this process asked Compose to create. */
export function managedComposeReadinessUrl(restPort: number): string {
  if (!Number.isInteger(restPort) || restPort < 1 || restPort > 65535) {
    throw new Error(`Invalid managed Compose REST port: ${restPort}`);
  }
  return `http://127.0.0.1:${restPort}`;
}

export async function withinStartupDeadline<T>(
  deadline: StartupDeadline,
  work: (signal: AbortSignal) => Promise<T>,
  maximumMs = Infinity,
): Promise<{ completed: true; value: T } | { completed: false }> {
  const remaining = Math.min(deadline.remaining(), maximumMs);
  if (remaining <= 0) return { completed: false };
  const controller = new AbortController();
  let timer: ReturnType<typeof setTimeout> | undefined;
  const expired = new Promise<{ completed: false }>((resolve) => {
    timer = setTimeout(() => {
      controller.abort();
      resolve({ completed: false });
    }, Math.ceil(remaining));
  });
  try {
    const result = await Promise.race([
      Promise.resolve().then(() => work(controller.signal)).then((value) => ({ completed: true as const, value })),
      expired,
    ]);
    return deadline.remaining() > 0 ? result : { completed: false };
  } finally {
    clearTimeout(timer);
    controller.abort();
  }
}

export async function waitForReadiness(
  deadline: StartupDeadline,
  probe: (signal: AbortSignal) => Promise<boolean>,
  options: { intervalMs?: number; probeTimeoutMs?: number; stopped?: () => boolean } = {},
): Promise<boolean> {
  while (deadline.remaining() > 0 && !options.stopped?.()) {
    const result = await withinStartupDeadline(deadline, probe, options.probeTimeoutMs ?? 1000).catch(() => ({ completed: false as const }));
    if (options.stopped?.()) return false;
    if (result.completed && result.value) return true;
    const remaining = deadline.remaining();
    if (remaining <= 0) break;
    const pause = Math.min(options.intervalMs ?? 250, remaining);
    if (pause > 0) await new Promise((resolve) => setTimeout(resolve, pause));
  }
  return false;
}

export async function probeEngine(base: string, signal: AbortSignal): Promise<boolean> {
  if (signal.aborted) return false;
  const response = await fetch(`${base}/`, { signal });
  // The engine's root path is normally 404 until the worker registers routes;
  // a response of any HTTP status proves the listener is reachable. Canceling
  // the body prevents a slow/streaming route from holding a probe open.
  void response.body?.cancel().catch(() => {});
  return true;
}

export async function probeWorker(
  base: string,
  signal: AbortSignal,
  onViewerPort?: (port: number) => void,
): Promise<boolean> {
  if (signal.aborted) return false;
  const response = await fetch(`${base}/agentmemory/livez`, { signal });
  if (!response.ok) {
    void response.body?.cancel().catch(() => {});
    return false;
  }
  const data: unknown = await response.json();
  if (!data || typeof data !== "object" || Array.isArray(data)) return false;
  const { viewerPort, viewerSkipped } = data as { viewerPort?: unknown; viewerSkipped?: unknown };
  if (typeof viewerPort === "number" && Number.isInteger(viewerPort) && viewerPort > 0 && viewerPort <= 65535) {
    onViewerPort?.(viewerPort);
    return true;
  }
  return viewerSkipped === true;
}

export async function startWorkerAndWait(options: {
  timeoutMs: number;
  hasLiveWorker: () => boolean;
  engineStartsWorker: () => boolean;
  startWorker: () => Promise<unknown>;
  probe: (signal: AbortSignal) => Promise<boolean>;
  stopped?: () => boolean;
}): Promise<boolean> {
  const deadline = startupDeadline(options.timeoutMs);
  if (options.stopped?.()) return false;
  if (!options.hasLiveWorker() && !options.engineStartsWorker()) {
    const started = await withinStartupDeadline(deadline, () => options.startWorker());
    if (!started.completed) return false;
  }
  return waitForReadiness(deadline, options.probe, { stopped: options.stopped });
}