Skip to content

armgit / qm

Public Imported from GitHub
0

Multiplayer agent harness for work.

12.2 KB
Raw Blame
import type { ExecResult } from "./sandbox.ts";
import { shq } from "../util/shell.ts";

export interface E2bCommandResult {
  stdout: string;
  stderr: string;
  exitCode: number;
}

interface E2bRunOpts {
  timeoutMs?: number;
}

export interface E2bMetrics {
  cpuUsedPct: number;
  cpuCount: number;
  memUsedBytes: number;
  memTotalBytes: number;
  diskUsedBytes: number;
  diskTotalBytes: number;
}

export interface E2bSession {
  readonly sandboxId: string;
  readonly trafficAccessToken?: string;
  host(port: number): string;
  runCommand(command: string, opts?: E2bRunOpts): Promise<E2bCommandResult>;

  readFileBytes(absPath: string): Promise<Uint8Array | null>;
  writeFileBytes(absPath: string, data: Uint8Array): Promise<void>;
  keepAlive(ms: number): Promise<void>;
  pause(): Promise<void>;
  createSnapshot(): Promise<{ snapshotId: string }>;
  metrics(): Promise<E2bMetrics | null>;
  kill(): Promise<void>;
}

interface E2bSandboxSummary {
  sandboxId: string;
  state: string;
  metadata?: Record<string, string>;
}

export interface E2bSandboxInfo {
  state: string;
  expiresAtMs: number;
  onTimeout?: string;
  cpuCount?: number;
  memoryMb?: number;
}

export class E2bSandboxGoneError extends Error {
  constructor(sandboxId: string, detail: string) {
    super(`e2b sandbox ${sandboxId} is gone: ${detail}`);
    this.name = "E2bSandboxGoneError";
  }
}

export class E2bCommandLostError extends Error {
  constructor(sandboxId: string, detail: string) {
    super(
      `e2b sandbox ${sandboxId} was lost while a command was running (${detail}); the command may have partially executed and was not retried`,
    );
    this.name = "E2bCommandLostError";
  }
}

interface E2bCreateOpts {
  metadata: Record<string, string>;
  timeoutMs?: number;
  autoPause?: boolean;
  autoResume?: boolean;
  fromSnapshot?: string;
}

export interface E2bClient {
  readonly nativePause?: boolean;
  info?(sandboxId: string): Promise<E2bSandboxInfo>;

  create(opts: E2bCreateOpts): Promise<E2bSession>;

  connect(sandboxId: string): Promise<E2bSession>;

  list(metadata: Record<string, string>): Promise<E2bSandboxSummary[]>;

  kill(sandboxId: string): Promise<void>;

  deleteSnapshot(snapshotId: string): Promise<void>;
}

export interface SdkE2bClientOptions {
  apiKey: string;
  templateId?: string;

  sandboxTtlMs?: number;

  maxLifetimeMs?: number;

  proxy?: string;

  maxCommandMs?: number;

  egressProxyUrl?: string;
}

interface SdkCommandResultLike {
  stdout?: string;
  stderr?: string;
  exitCode?: number;
}

export interface E2bEgressNetwork {
  allowOut: string[];
  denyOut: string[];
}

const DEFAULT_TEMPLATE = "base";
const DEFAULT_TTL_MS = 15 * 60_000;
const DEFAULT_MAX_COMMAND_MS = 3600_000;
const E2B_PRO_MAX_LIFETIME_MS = 24 * 3600_000;
export const E2B_EXEC_MARGIN_MS = 60_000;

export async function runE2bScript(session: E2bSession, script: string, timeoutSec: number): Promise<ExecResult> {
  const r = await session.runCommand(`timeout ${timeoutSec} sh -c ${shq(script)}`, {
    timeoutMs: timeoutSec * 1000 + 30_000,
  });
  return { stdout: r.stdout, stderr: r.stderr, code: r.exitCode, timedOut: r.exitCode === 124 };
}
const ALL_TRAFFIC = "0.0.0.0/0";

const HOSTNAME_MATCHED_PORTS: Record<string, string> = { "http:": "80", "https:": "443" };

export function e2bEgressNetwork(egressProxyUrl: string): E2bEgressNetwork {
  const url = new URL(egressProxyUrl);
  const host = url.hostname.replace(/^\[|\]$/g, "");
  const port = url.port || HOSTNAME_MATCHED_PORTS[url.protocol] || "";
  const ipLiteral = /^[\d.]+$/.test(host) || host.includes(":");
  if (!ipLiteral && port !== "80" && port !== "443")
    throw new Error(
      `E2B egress proxy ${egressProxyUrl}: E2B matches allowed hostnames only on ports 80 and 443; give the proxy on one of those ports or by IP address`,
    );
  return { allowOut: [host], denyOut: [ALL_TRAFFIC] };
}

function e2bSandboxTtlMs(opts: Pick<SdkE2bClientOptions, "sandboxTtlMs" | "maxLifetimeMs" | "maxCommandMs">): {
  sandboxTtlMs: number;
  maxLifetimeMs: number;
  maxCommandMs: number;
} {
  const maxLifetimeMs = opts.maxLifetimeMs ?? E2B_PRO_MAX_LIFETIME_MS;
  if (!Number.isFinite(maxLifetimeMs) || maxLifetimeMs <= E2B_EXEC_MARGIN_MS)
    throw new Error(`e2b maxLifetimeMs must be a finite number of milliseconds above ${E2B_EXEC_MARGIN_MS}`);
  const maxCommandMs = Math.min(opts.maxCommandMs ?? DEFAULT_MAX_COMMAND_MS, maxLifetimeMs - E2B_EXEC_MARGIN_MS);
  const requested = opts.sandboxTtlMs ?? Math.max(DEFAULT_TTL_MS, maxCommandMs + E2B_EXEC_MARGIN_MS);
  return { sandboxTtlMs: Math.min(maxLifetimeMs, requested), maxLifetimeMs, maxCommandMs };
}

function commandResultFrom(value: unknown): E2bCommandResult | null {
  const r = value as SdkCommandResultLike & { result?: SdkCommandResultLike };
  let source: SdkCommandResultLike | null = null;
  if (typeof r?.exitCode === "number") source = r;
  else if (typeof r?.result?.exitCode === "number") source = r.result;
  if (!source) return null;
  return { stdout: source.stdout ?? "", stderr: source.stderr ?? "", exitCode: source.exitCode ?? -1 };
}

type E2bSdk = typeof import("e2b");

const SANDBOX_TIMEOUT_MESSAGE = /sandbox timeout|end of life|not running anymore/i;

function isSandboxGone(sdk: E2bSdk, err: unknown): boolean {
  if (err instanceof sdk.SandboxNotFoundError) return true;
  return err instanceof sdk.TimeoutError && SANDBOX_TIMEOUT_MESSAGE.test(err.message);
}

export function createSdkE2bClient(opts: SdkE2bClientOptions): E2bClient {
  const templateId = opts.templateId ?? DEFAULT_TEMPLATE;
  const { sandboxTtlMs, maxLifetimeMs, maxCommandMs } = e2bSandboxTtlMs(opts);
  const network = opts.egressProxyUrl ? e2bEgressNetwork(opts.egressProxyUrl) : undefined;
  const common = {
    apiKey: opts.apiKey,
    ...(opts.proxy ? { proxy: opts.proxy } : {}),
  };

  let sdk: Promise<E2bSdk> | null = null;
  const loadSdk = (): Promise<E2bSdk> => {
    const loaded = (sdk ??= import("e2b").then(
      (m) => m as unknown as E2bSdk,
      (e) => {
        sdk = null;
        throw new Error(`the e2b SDK is not installed: ${String((e as Error)?.message ?? e)}`);
      },
    ));
    return loaded;
  };

  type SdkSandbox = Awaited<ReturnType<E2bSdk["Sandbox"]["create"]>>;

  const wrap = (lib: E2bSdk, sbx: SdkSandbox, ttlMs: number): E2bSession => {
    let expiresAtMs = Date.now() + ttlMs;
    const gone = (err: unknown): unknown =>
      isSandboxGone(lib, err) ? new E2bSandboxGoneError(sbx.sandboxId, String((err as Error).message)) : err;
    const extend = async (ms: number): Promise<void> => {
      const bounded = Math.min(maxLifetimeMs, Math.max(ms, expiresAtMs - Date.now()));
      const at = Date.now() + bounded;
      try {
        await sbx.setTimeout(bounded);
      } catch (err) {
        throw gone(err);
      }
      expiresAtMs = at;
    };
    const cover = async (commandMs: number): Promise<void> => {
      const needed = Math.min(commandMs, maxCommandMs) + E2B_EXEC_MARGIN_MS;
      if (Date.now() + needed <= expiresAtMs) return;
      await extend(Math.max(ttlMs, needed));
    };
    return {
      sandboxId: sbx.sandboxId,
      ...(sbx.trafficAccessToken ? { trafficAccessToken: sbx.trafficAccessToken } : {}),
      host: (port) => sbx.getHost(port),
      async runCommand(command, runOpts): Promise<E2bCommandResult> {
        const timeoutMs = runOpts?.timeoutMs ?? maxCommandMs;
        await cover(timeoutMs);
        let handle: Awaited<ReturnType<SdkSandbox["commands"]["run"]>>;
        try {
          handle = await sbx.commands.run(command, { background: true, timeoutMs });
        } catch (err) {
          if (isSandboxGone(lib, err)) throw new E2bCommandLostError(sbx.sandboxId, String((err as Error).message));
          throw err;
        }
        try {
          return commandResultFrom(await handle.wait()) ?? { stdout: "", stderr: "", exitCode: -1 };
        } catch (err) {
          const asResult = commandResultFrom(err);
          if (asResult) return asResult;
          if (isSandboxGone(lib, err)) throw new E2bCommandLostError(sbx.sandboxId, String((err as Error).message));
          throw err;
        }
      },
      async readFileBytes(absPath): Promise<Uint8Array | null> {
        try {
          const data = await sbx.files.read(absPath, { format: "bytes" });
          return data instanceof Uint8Array ? data : new Uint8Array(data as ArrayBuffer);
        } catch (err) {
          if (err instanceof lib.FileNotFoundError) return null;
          throw gone(err);
        }
      },
      async writeFileBytes(absPath, data): Promise<void> {
        const buf = new ArrayBuffer(data.byteLength);
        new Uint8Array(buf).set(data);
        try {
          await sbx.files.write(absPath, buf);
        } catch (err) {
          throw gone(err);
        }
      },
      keepAlive: (ms) => extend(ms),
      async pause(): Promise<void> {
        try {
          await sbx.pause({ keepMemory: true });
        } catch (err) {
          throw gone(err);
        }
      },
      async createSnapshot(): Promise<{ snapshotId: string }> {
        try {
          const info = await sbx.createSnapshot();
          return { snapshotId: info.snapshotId };
        } catch (err) {
          throw gone(err);
        }
      },
      async metrics(): Promise<E2bMetrics | null> {
        const rows = await sbx.getMetrics();
        const last = rows.at(-1);
        if (!last) return null;
        return {
          cpuUsedPct: last.cpuUsedPct,
          cpuCount: last.cpuCount,
          memUsedBytes: last.memUsed,
          memTotalBytes: last.memTotal,
          diskUsedBytes: last.diskUsed,
          diskTotalBytes: last.diskTotal,
        };
      },
      async kill(): Promise<void> {
        await sbx.kill().catch((err) => {
          if (!isSandboxGone(lib, err)) throw err;
        });
      },
    };
  };

  return {
    nativePause: true,
    async info(sandboxId) {
      const lib = await loadSdk();
      try {
        const info = await lib.Sandbox.getInfo(sandboxId, common);
        return {
          state: info.state,
          expiresAtMs: info.endAt.getTime(),
          onTimeout: info.lifecycle?.onTimeout,
          cpuCount: info.cpuCount,
          memoryMb: info.memoryMB,
        };
      } catch (err) {
        if (isSandboxGone(lib, err)) throw new E2bSandboxGoneError(sandboxId, String((err as Error).message));
        throw err;
      }
    },
    async create(createOpts): Promise<E2bSession> {
      const lib = await loadSdk();
      const timeoutMs = Math.min(maxLifetimeMs, createOpts.timeoutMs ?? sandboxTtlMs);
      const sbx = await lib.Sandbox.create(createOpts.fromSnapshot ?? templateId, {
        ...common,
        timeoutMs,
        metadata: createOpts.metadata,
        lifecycle: {
          onTimeout: createOpts.autoPause ? "pause" : "kill",
          autoResume: !!(createOpts.autoPause && createOpts.autoResume),
        },
        network: { ...network, allowPublicTraffic: false },
      });
      return wrap(lib, sbx, timeoutMs);
    },
    async connect(sandboxId): Promise<E2bSession> {
      const lib = await loadSdk();
      try {
        const sbx = await lib.Sandbox.connect(sandboxId, { ...common, timeoutMs: sandboxTtlMs });
        if (network) await sbx.updateNetwork(network);
        return wrap(lib, sbx, sandboxTtlMs);
      } catch (err) {
        if (isSandboxGone(lib, err)) throw new E2bSandboxGoneError(sandboxId, String((err as Error).message));
        throw err;
      }
    },
    async list(metadata): Promise<E2bSandboxSummary[]> {
      const { Sandbox } = await loadSdk();
      const paginator = Sandbox.list({
        ...common,
        ...(Object.keys(metadata).length ? { query: { metadata } } : {}),
      });
      const out: E2bSandboxSummary[] = [];
      while (paginator.hasNext) {
        const items = await paginator.nextItems();
        for (const s of items) {
          out.push({ sandboxId: s.sandboxId, state: String(s.state), ...(s.metadata ? { metadata: s.metadata } : {}) });
        }
      }
      return out;
    },
    async kill(sandboxId): Promise<void> {
      const lib = await loadSdk();
      await lib.Sandbox.kill(sandboxId, common).catch((err) => {
        if (!isSandboxGone(lib, err)) throw err;
      });
    },
    async deleteSnapshot(snapshotId): Promise<void> {
      const { Sandbox } = await loadSdk();
      await Sandbox.deleteSnapshot(snapshotId, common);
    },
  };
}