Skip to content

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

10.4 KB
Raw Blame
import { chmodSync, closeSync, fstatSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, writeFileSync } from "node:fs";
import { dirname } from "node:path";
import { spawn, type ChildProcess } from "node:child_process";
import { createConnection } from "node:net";
import { join } from "node:path";
import { registerWorker } from "iii-sdk";
import { composeNamespace, type ComposeProjectOptions, writeWorkerCompose, COMPOSE_WORKER_VERSIONS } from "./compose-project.js";

export interface ComposeRuntime extends ComposeProjectOptions {
  namespace?: string;
  stateDir: string;
  logFile: string;
  envFile?: string;
  iiiBin: string;
  env: NodeJS.ProcessEnv;
}

export function composeRegistryFailureMessage(logText: string, workerBinDir?: string): string | null {
  const patterns = [
    /REGISTRY_UNREACHABLE|REGISTRY_ERROR|PACKAGE_DOWNLOAD_FAILED/i,
    /cannot reach the registry/i,
    /registry (?:returned|responded|response)[^\n]*HTTP 5\d\d|HTTP 5\d\d[^\n]*registry/i,
    /failed to resolve (?:a )?package|package resolution (?:failed|unavailable)|could not resolve .*registry/i,
    /could not download https:\/\/api\.workers\.iii\.dev\/download\//i,
  ];
  if (!patterns.some((pattern) => pattern.test(logText))) return null;
  const localWorkers = workerBinDir ? ` Configured local workers directory: ${workerBinDir}.` : "";
  return `Worker registry unavailable while resolving state/http; retry later or set AGENTMEMORY_WORKER_BIN_DIR.${localWorkers}`;
}

export function composeStateRegistryFailure(dataDir: string, file: string): string | null {
  const stateRoot = join(dataDir, "compose-state");
  try {
    const files = [] as string[];
    const walk = (dir: string) => {
      for (const entry of readdirSync(dir, { withFileTypes: true })) {
        const path = join(dir, entry.name);
        if (entry.isDirectory()) walk(path);
        else if (entry.name === "state.json") files.push(path);
      }
    };
    walk(stateRoot);
    for (const stateFile of files) {
      const state = JSON.parse(readFileSync(stateFile, "utf8")) as { compose_path?: string; containers?: Record<string, { status?: string; last_error?: string }> };
      const errors = Object.entries(state.containers ?? {}).filter(([, value]) => value.status === "failed").map(([name, value]) => `${name}: ${value.last_error ?? "failed"}`);
      const message = errors.join("\n");
      if (state.compose_path !== file) continue;
      if (message && composeRegistryFailureMessage(message)) return message;
    }
  } catch {}
  return null;
}

export function composeWorkerFailureSummary(project: ComposeProjectStatus | null): string | null {
  if (!project) return null;
  const failed = (project.containers ?? []).filter((container) => container.state === "failed");
  if (!failed.length) return null;
  return failed.map((container) => `${container.container ?? "worker"}: ${container.last_error ?? "failed after restart attempts were exhausted"}`).join("\n");
}

export type ComposeContainerStatus = { container?: string; state?: string; version?: string; pid?: number; owned?: boolean; log_path?: string; last_error?: string };
export type ComposeProjectStatus = { file?: string; state_dir?: string; namespace?: string; daemon_pid?: number; containers?: ComposeContainerStatus[]; [key: string]: unknown };
export type ComposeStatus = ComposeProjectStatus & {
  daemon_pid?: number;
  projects?: Array<{ file?: string; state_dir?: string; [key: string]: unknown }>;
};

export function ownedComposeProject(status: ComposeStatus, file: string): ComposeProjectStatus | null {
  return status.file === file ? status : status.projects?.find((item) => item.file === file) ?? null;
}

function cleanDaemonEnv(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
  const out: NodeJS.ProcessEnv = {};
  for (const key of ["HOME", "PATH", "LANG", "LC_ALL", "TERM", "NO_COLOR", "III_TELEMETRY_ENABLED", "MALLOC_ARENA_MAX", "III_BUNDLE_WORKERS_DISABLED", "III_COMPOSE_MAX_PARALLEL_WORKERS", "AGENTMEMORY_TOOLS", "AGENTMEMORY_VIEWER_HOST", "VIEWER_ALLOWED_HOSTS", "VIEWER_ALLOWED_ORIGINS"]) {
    const value = env[key];
    if (value !== undefined) out[key] = value;
  }
  return out;
}

export async function probeComposeEngine(port: number, signal: AbortSignal): Promise<boolean> {
  if (signal.aborted) return false;
  return await new Promise<boolean>((resolve) => {
    const socket = createConnection({ host: "127.0.0.1", port });
    let settled = false;
    const finish = (ready: boolean) => {
      if (settled) return;
      settled = true;
      signal.removeEventListener("abort", abort);
      socket.destroy();
      resolve(ready);
    };
    const abort = () => finish(false);
    // The caller normally supplies a larger engine-readiness deadline. Keep
    // each TCP probe bounded independently so a half-open route/proxy can never
    // pin one iteration until the whole startup budget expires.
    socket.setTimeout(1000);
    socket.once("connect", () => finish(true));
    socket.once("error", () => finish(false));
    socket.once("timeout", () => finish(false));
    signal.addEventListener("abort", abort, { once: true });
  });
}

export async function assertComposePortsFree(ports: readonly number[]): Promise<void> {
  for (const port of [...new Set(ports)]) {
    const occupied = await new Promise<boolean>((resolve) => {
      const socket = createConnection({ host: "127.0.0.1", port });
      const done = (value: boolean) => { socket.destroy(); resolve(value); };
      socket.setTimeout(350);
      socket.once("connect", () => done(true));
      socket.once("timeout", () => done(false));
      socket.once("error", () => done(false));
    });
    if (occupied) throw new Error(`Port ${port} is already in use on 127.0.0.1. Stop the process that owns it or choose another --port/--instance before starting agentmemory.`);
  }
}

export function composeEnvironment(env: NodeJS.ProcessEnv, stateDir: string): NodeJS.ProcessEnv {
  return {
    ...cleanDaemonEnv(env),
    III_COMPOSE_STATE_DIR: stateDir,
    III_TELEMETRY_ENABLED: "false",
    ...(process.platform === "linux" ? { MALLOC_ARENA_MAX: "2" } : {}),
    ...(env.AGENTMEMORY_DISABLE_COMPOSE_RESTART === "1" ? { AGENTMEMORY_DISABLE_COMPOSE_RESTART: "1" } : {}),
  };
}

export async function composeCall<T>(options: {
  engineUrl: string;
  namespace: string;
  functionId: "compose::down" | "compose::status";
  file: string;
  timeoutMs?: number;
}): Promise<T> {
  const client = registerWorker(options.engineUrl, {
    workerName: "agentmemory-cli",
    namespace: options.namespace,
    invocationTimeoutMs: options.timeoutMs ?? 30_000,
    otel: { enabled: false },
    enableMetricsReporting: false,
  });
  try {
    const connectionDeadline = Date.now() + 8_000;
    while (client.getConnectionState() !== "connected" && Date.now() < connectionDeadline) {
      const fatal = client.getFatalError();
      if (fatal) throw fatal;
      await new Promise((resolve) => setTimeout(resolve, 50));
    }
    if (client.getConnectionState() !== "connected") throw new Error("Could not connect the Compose control client to its instance engine.");
    const deadline = Date.now() + 8_000;
    let lastError: unknown;
    while (Date.now() < deadline) {
      try {
        const result = await client.trigger<T & { status?: string; error?: { code?: string; message?: string } }>({
          function_id: options.functionId,
          payload: { file: options.file },
          timeoutMs: options.timeoutMs ?? 30_000,
        });
        if (result && typeof result === "object" && result.status === "failed") {
          const detail = result.error?.message ?? result.error?.code ?? "unknown Compose failure";
          throw Object.assign(new Error(`${result.error?.code ? `${result.error.code}: ` : ""}${detail}`), { retryable: false });
        }
        return result;
      } catch (err) {
        lastError = err;
        if (err && typeof err === "object" && "retryable" in err && (err as { retryable?: boolean }).retryable === false) throw err;
        await new Promise((resolve) => setTimeout(resolve, 150));
      }
    }
    throw lastError ?? new Error("Compose daemon did not accept the control connection.");
  } finally {
    await client.shutdown().catch(() => {});
  }
}

export function startComposeDaemon(runtime: ComposeRuntime): { child: ChildProcess; file: string; namespace: string; stateDir: string; logFile: string; logStartOffset: number } {
  const project = writeWorkerCompose({ ...runtime, envFile: runtime.envFile });
  const logFile = runtime.logFile;
  mkdirSync(dirname(logFile), { recursive: true, mode: 0o700 });
  chmodSync(dirname(logFile), 0o700);
  const fd = openSync(logFile, "a", 0o600);
  const logStartOffset = fstatSync(fd).size;
  writeFileSync(fd, `\n[${new Date().toISOString()}] Starting Worker Compose\n`);
  const environment = composeEnvironment(runtime.env, project.stateDir);
  const child = spawn(runtime.iiiBin, ["compose", "--namespace", composeNamespace(runtime.ports.restPort), "--up", "--file", project.file], {
    cwd: runtime.projectRoot,
    detached: true,
    stdio: ["ignore", fd, fd],
    windowsHide: true,
    env: environment,
  });
  closeSync(fd);
  child.unref();
  return {
    child,
    file: project.file,
    namespace: composeNamespace(runtime.ports.restPort),
    stateDir: project.stateDir,
    logFile,
    logStartOffset,
  };
}

export function readComposeLogFromOffset(file: string, offset: number): string {
  const fd = openSync(file, "r");
  try {
    const size = fstatSync(fd).size;
    let position = Math.min(Math.max(0, offset), size);
    const chunks: Buffer[] = [];
    while (position < size) {
      const chunk = Buffer.allocUnsafe(Math.min(16 * 1024, size - position));
      const count = readSync(fd, chunk, 0, chunk.length, position);
      if (count === 0) break;
      chunks.push(chunk.subarray(0, count));
      position += count;
    }
    return Buffer.concat(chunks).toString("utf8");
  } finally {
    closeSync(fd);
  }
}

export function writeComposeState(path: string, state: {
  kind: "compose";
  restPort: number;
  viewerPort: number;
  enginePort: number;
  engineUrl: string;
  namespace: string;
  file: string;
  stateDir: string;
  logFile: string;
  logStartOffset?: number;
  binPath: string;
  enginePid?: number;
  workerBinDir?: string;
  workerFailure?: string;
  workerVersions: typeof COMPOSE_WORKER_VERSIONS | { local: true };
}): void {
  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
  writeFileSync(path, `${JSON.stringify(state)}\n`, { encoding: "utf8", mode: 0o600 });
  chmodSync(path, 0o600);
}