@prismatic-io/lux 0.0.2-preview.27 → 0.0.2-preview.29

package/src/container/driver.ts

@@ -0,0 +1,211 @@
+import { realpath } from "node:fs/promises";
+import { resolve, sep } from "node:path";
+import type { AgentDriver, Artifact, DriverEventMap, StartContext } from "../core/driver.js";
+import type { ContainerExecution } from "../core/driver-execution.js";
+import { TypedEmitter } from "../core/emitter.js";
+import {
+  type Answer,
+  DoneSchema,
+  ErrorEventSchema,
+  InterruptSchema,
+  ProgressSchema,
+  type ReadyState,
+  ReadyStateSchema,
+} from "../core/events.js";
+import { type ManagedProcess, spawnManagedProcess } from "../core/exec.js";
+import { walkArtifacts } from "../drivers/shared/artifacts.js";
+import { LUX_VERSION } from "../orchestrator/package-version.js";
+import { type Message, readMessages, writeMessage } from "./protocol.js";
+import { prepareContainer } from "./resources.js";
+
+export class ContainerDriver extends TypedEmitter<DriverEventMap> implements AgentDriver {
+  private process: ManagedProcess | undefined;
+  private resources: Awaited<ReturnType<typeof prepareContainer>> | undefined;
+  private sequence = 0;
+  private pending = new Map<
+    number,
+    { resolve: (value: unknown) => void; reject: (error: Error) => void }
+  >();
+  private closing: Promise<void> | undefined;
+  private context: StartContext | undefined;
+  private terminal = false;
+  private readonly abort = () => {
+    void this.close().catch(() => {});
+  };
+
+  private readonly name: string;
+  private readonly config: unknown;
+  private readonly execution: ContainerExecution;
+  constructor(name: string, config: unknown, execution: ContainerExecution) {
+    super();
+    this.name = name;
+    this.config = config;
+    this.execution = execution;
+    JSON.stringify(config, (_key, value: unknown) => {
+      if (typeof value === "function" || typeof value === "symbol" || typeof value === "bigint")
+        throw new Error("container driver configuration must be JSON serializable");
+      return value;
+    });
+  }
+
+  private fail = (error: Error): void => {
+    for (const pending of this.pending.values()) pending.reject(error);
+    this.pending.clear();
+    if (!this.terminal && !this.closing) {
+      this.terminal = true;
+      void this.emit("error", { exitReason: "error", reason: error.message }).catch(() => {});
+    }
+  };
+
+  private receive = (message: Message): void => {
+    if (message.event) {
+      const dispatch = async () => {
+        switch (message.event) {
+          case "interrupt":
+            await this.emit("interrupt", InterruptSchema.parse(message.value));
+            break;
+          case "progress":
+            await this.emit("progress", ProgressSchema.parse(message.value));
+            break;
+          case "done":
+            this.terminal = true;
+            await this.emit("done", DoneSchema.parse(message.value));
+            break;
+          case "error":
+            this.terminal = true;
+            await this.emit("error", ErrorEventSchema.parse(message.value));
+            break;
+          default:
+            throw new Error("unknown container event");
+        }
+        if (this.process) writeMessage(this.process.child.stdin, { id: message.id, ack: true });
+      };
+      void dispatch().catch(this.fail);
+      return;
+    }
+    const pending = this.pending.get(message.id);
+    if (!pending) return;
+    this.pending.delete(message.id);
+    if (message.error !== undefined) pending.reject(new Error(message.error));
+    else pending.resolve(message.value);
+  };
+
+  private rpc = (method: string, value?: unknown, timeoutMs = 30_000): Promise<unknown> =>
+    new Promise((resolvePromise, reject) => {
+      if (!this.process) {
+        reject(new Error("container process is unavailable"));
+        return;
+      }
+      const id = ++this.sequence;
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error(`container ${method} timed out`));
+      }, timeoutMs);
+      this.pending.set(id, {
+        resolve: (result) => {
+          clearTimeout(timer);
+          resolvePromise(result);
+        },
+        reject: (error) => {
+          clearTimeout(timer);
+          reject(error);
+        },
+      });
+      try {
+        writeMessage(this.process.child.stdin, { id, method, value });
+      } catch (error) {
+        this.pending.get(id)?.reject(error as Error);
+        this.pending.delete(id);
+      }
+    });
+
+  async start(ctx: StartContext): Promise<ReadyState> {
+    this.context = ctx;
+    if (ctx.abortSignal.aborted) throw new Error("container run aborted before startup");
+    const raw = this.config as { cwd?: string; cwdMode?: string };
+    if (raw?.cwdMode === "runDir")
+      throw new Error("container drivers must use the artifacts workspace, not cwdMode: runDir");
+    if (raw?.cwd && (await realpath(raw.cwd)) !== (await realpath(ctx.artifactsDir)))
+      throw new Error("container driver cwd must be the mounted artifacts workspace");
+    this.resources = await prepareContainer(this.execution, ctx.artifactsDir);
+    try {
+      this.process = spawnManagedProcess(this.resources.command, this.resources.args, {
+        env: this.resources.env,
+      });
+      readMessages(this.process.child.stdout, this.receive, this.fail);
+      // Harness stderr can contain secrets. The normalized driver protocol is the evidence surface.
+      this.process.child.stderr.resume();
+      void this.process.exited.then(() => this.fail(new Error("container worker exited")));
+      ctx.abortSignal.addEventListener("abort", this.abort, { once: true });
+      await this.process.spawned;
+      if (ctx.abortSignal.aborted) throw new Error("container run aborted during startup");
+      const { abortSignal: _signal, ...context } = ctx;
+      const ready = ReadyStateSchema.parse(
+        await this.rpc(
+          "start",
+          {
+            version: LUX_VERSION,
+            name: this.name,
+            config: this.config,
+            module: this.execution.driverModule,
+            context: {
+              ...context,
+              artifactsDir: this.resources.root,
+              ...(context.fixtures
+                ? { fixtures: { ...context.fixtures, rootDir: this.resources.root } }
+                : {}),
+              runDir: "/tmp/lux-run",
+              runsRoot: "/tmp/lux-runs",
+            },
+          },
+          this.execution.startupTimeoutMs ?? 60_000,
+        ),
+      );
+      return {
+        ...ready,
+        detail: { ...ready.detail, execution: "container", image: this.resources.image },
+      };
+    } catch (error) {
+      await this.close();
+      throw error;
+    }
+  }
+
+  async respond(answer: Answer): Promise<void> {
+    await this.rpc("respond", answer);
+  }
+  async quiesce(): Promise<void> {
+    await this.rpc("quiesce");
+  }
+  async collect(): Promise<Artifact[]> {
+    const root = this.resources?.root;
+    if (!root) return [];
+    try {
+      const artifacts = (await this.rpc("collect")) as Artifact[];
+      for (const artifact of artifacts) {
+        const path = resolve(artifact.root ?? root, artifact.path);
+        if (path !== root && !path.startsWith(`${root}${sep}`))
+          throw new Error("container driver returned artifacts outside its mounted workspace");
+      }
+    } finally {
+      await this.close();
+    }
+    return walkArtifacts(root);
+  }
+  close(): Promise<void> {
+    this.closing ??= (async () => {
+      this.context?.abortSignal.removeEventListener("abort", this.abort);
+      try {
+        if (this.process) {
+          await this.rpc("close", undefined, 5_000).catch(() => {});
+          this.process.child.stdin.end();
+        }
+        await this.resources?.cleanup();
+      } finally {
+        await this.process?.terminate();
+        this.fail(new Error("container driver closed"));
+      }
+    })();
+    return this.closing;
+  }
+}

package/src/container/protocol.ts

@@ -0,0 +1,48 @@
+import type { Readable, Writable } from "node:stream";
+
+export type Message = {
+  id: number;
+  method?: string;
+  event?: string;
+  value?: unknown;
+  error?: string;
+  ack?: boolean;
+};
+export const writeMessage = (stream: Writable, message: Message): void => {
+  const line = JSON.stringify(message);
+  if (line.length > 8_000_000) throw new Error("container protocol message exceeds 8 MB");
+  stream.write(`${line}\n`);
+};
+export const readMessages = (
+  stream: Readable,
+  receive: (message: Message) => void,
+  fail: (error: Error) => void,
+): void => {
+  let buffer = "";
+  stream.setEncoding("utf8");
+  stream.on("data", (chunk: string) => {
+    try {
+      buffer += chunk;
+      for (;;) {
+        const newline = buffer.indexOf("\n");
+        if (newline < 0) break;
+        if (newline > 8_000_000) throw new Error("container protocol message exceeds 8 MB");
+        const message: unknown = JSON.parse(buffer.slice(0, newline));
+        buffer = buffer.slice(newline + 1);
+        if (
+          !message ||
+          typeof message !== "object" ||
+          !("id" in message) ||
+          !Number.isSafeInteger(message.id)
+        )
+          throw new Error("invalid container protocol message");
+        receive(message as Message);
+      }
+      if (buffer.length > 8_000_000) throw new Error("container protocol buffer exceeds 8 MB");
+    } catch (error) {
+      buffer = "";
+      stream.pause();
+      fail(error instanceof Error ? error : new Error(String(error)));
+    }
+  });
+};

package/src/container/resources.ts

@@ -0,0 +1,153 @@
+import { randomUUID } from "node:crypto";
+import { chmod, copyFile, lstat, mkdir, mkdtemp, realpath, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import type { ContainerExecution } from "../core/driver-execution.js";
+import { exec } from "../core/exec.js";
+
+const mount = (source: string, target: string, readOnly = false): string => {
+  if ([source, target].some((path) => !isAbsolute(path) || /[,\r\n\0]/u.test(path)))
+    throw new Error(
+      "container mount paths must be absolute and contain no commas or control characters",
+    );
+  return `type=bind,source=${source},target=${target}${readOnly ? ",readonly" : ""}`;
+};
+
+export const prepareContainer = async (config: ContainerExecution, workspace: string) => {
+  const command = config.command ?? "docker";
+  const inspected = await exec(command, ["image", "inspect", "--format", "{{.Id}}", config.image], {
+    timeoutMs: config.startupTimeoutMs ?? 30_000,
+    maxBuffer: 4096,
+  });
+  if (inspected.exitCode !== 0 || !/^sha256:[a-f0-9]{64}$/u.test(inspected.stdout.trim()))
+    throw new Error(
+      "container image is unavailable; build or pull the configured image before running Lux",
+    );
+  const image = inspected.stdout.trim();
+  const home = await mkdtemp(join(tmpdir(), "lux-container-home-"));
+  const name = `lux-${randomUUID()}`;
+  const cleanup = async () => {
+    // Killing the Docker client does not stop the daemon-owned container.
+    const removed = await exec(command, ["rm", "--force", name], {
+      timeoutMs: 15_000,
+      maxBuffer: 4096,
+    });
+    if (removed.exitCode !== 0 && !removed.stderr.includes("No such container"))
+      throw new Error(
+        `failed to remove owned container '${name}'; private home retained at ${home}`,
+      );
+    await rm(home, { recursive: true, force: true });
+  };
+  try {
+    await chmod(home, 0o700);
+    for (const file of config.homeFiles ?? []) {
+      const target = join(home, file.destination);
+      await mkdir(dirname(target), { recursive: true, mode: 0o700 });
+      if (file.source.kind === "file") {
+        if (!(await lstat(file.source.path)).isFile())
+          throw new Error("container home credential source must be a regular file");
+        await copyFile(file.source.path, target);
+      } else {
+        if (process.platform !== "darwin")
+          throw new Error("container Keychain credentials require macOS");
+        const result = await exec(
+          "/usr/bin/security",
+          ["find-generic-password", "-s", file.source.service, "-a", file.source.account, "-w"],
+          { timeoutMs: 10_000, maxBuffer: 1_000_000 },
+        );
+        if (result.exitCode !== 0 || result.stdoutTruncated)
+          throw new Error("could not read the explicitly configured container Keychain credential");
+        const value = result.stdout.trimEnd();
+        await writeFile(
+          target,
+          file.source.encoding === "go-keyring-base64" && value.startsWith("go-keyring-base64:")
+            ? Buffer.from(value.slice("go-keyring-base64:".length), "base64")
+            : value,
+          { mode: 0o600 },
+        );
+      }
+      await chmod(target, 0o600);
+    }
+    const root = await realpath(workspace);
+    const args = [
+      "run",
+      "--init",
+      "-i",
+      "--pull",
+      "never",
+      "--name",
+      name,
+      "--read-only",
+      "--cap-drop",
+      "ALL",
+      "--security-opt",
+      "no-new-privileges",
+      "--network",
+      config.network ?? "bridge",
+      "--memory",
+      config.memory ?? "4g",
+      "--cpus",
+      String(config.cpus ?? 2),
+      "--pids-limit",
+      String(config.pidsLimit ?? 512),
+      "--user",
+      config.user ?? `${process.getuid?.() ?? 1000}:${process.getgid?.() ?? 1000}`,
+      "--tmpfs",
+      "/tmp:rw,nosuid,nodev,exec,size=1g,mode=1777",
+      "--workdir",
+      root,
+      "--mount",
+      mount(root, root),
+      "--mount",
+      mount(await realpath(home), "/home/lux"),
+      "--env",
+      "HOME=/home/lux",
+      "--env",
+      "npm_config_yes=true",
+    ];
+    for (const entry of config.mounts ?? []) {
+      const source = await realpath(entry.source);
+      const target = resolve(entry.target ?? source);
+      if (
+        [
+          "/",
+          "/home",
+          "/home/lux",
+          "/tmp",
+          "/opt",
+          "/opt/lux",
+          "/usr",
+          "/bin",
+          "/etc",
+          "/proc",
+          "/sys",
+          "/dev",
+        ].some(
+          (reserved) =>
+            target === reserved || (reserved !== "/" && target.startsWith(`${reserved}/`)),
+        ) ||
+        target === root ||
+        root.startsWith(`${target}/`) ||
+        target.startsWith(`${root}/`)
+      )
+        throw new Error(
+          "additional container mounts must not overlap the workspace or runtime paths",
+        );
+      args.push("--mount", mount(source, target, entry.readOnly ?? true));
+    }
+    const env = { ...process.env };
+    for (const key of new Set([...(config.passEnv ?? []), ...Object.keys(config.env ?? {})])) {
+      if (["HOME", "NODE_OPTIONS", "NODE_PATH", "LD_PRELOAD", "LD_LIBRARY_PATH"].includes(key))
+        throw new Error(`reserved container environment variable '${key}'`);
+      const value = config.env?.[key] ?? process.env[key];
+      if (value === undefined) throw new Error(`container environment variable '${key}' is unset`);
+      env[key] = value;
+      args.push("--env", key);
+    }
+    args.push("--entrypoint", "node", image, config.worker ?? "/opt/lux/lib/container/worker.js");
+    return { command, args, env, image, root, cleanup };
+  } catch (error) {
+    await rm(home, { recursive: true, force: true });
+    throw error;
+  }
+};

package/src/container/worker.ts

@@ -0,0 +1,107 @@
+import { mkdir } from "node:fs/promises";
+import type { AgentDriver, DriverPlugin, StartContext } from "../core/driver.js";
+import { AnswerSchema } from "../core/events.js";
+import { buildRegistryFromConfig, LuxConfigSchema } from "../orchestrator/config.js";
+import { LUX_VERSION } from "../orchestrator/package-version.js";
+import { validatePluginConfig } from "../orchestrator/validate-plugin-config.js";
+import { type Message, readMessages, writeMessage } from "./protocol.js";
+
+let driver: AgentDriver | undefined;
+let eventId = 0;
+const acknowledgements = new Map<number, () => void>();
+const abort = new AbortController();
+const dispatch = async (message: Message): Promise<unknown> => {
+  if (message.method === "start") {
+    if (driver) throw new Error("container driver already started");
+    const request = message.value as {
+      version: string;
+      name: string;
+      module?: string;
+      config: unknown;
+      context: Omit<StartContext, "abortSignal">;
+    };
+    if (request.version !== LUX_VERSION)
+      throw new Error("container worker and host Lux versions differ; rebuild the image");
+    const plugin: DriverPlugin | undefined = request.module
+      ? (await import(request.module)).default
+      : buildRegistryFromConfig({
+          ...LuxConfigSchema.parse({}),
+          rootDir: process.cwd(),
+          configPath: null,
+        }).getDriver(request.name);
+    if (!plugin || plugin.name !== request.name)
+      throw new Error("container driver plugin is unavailable");
+    driver = await plugin.create(
+      validatePluginConfig(
+        plugin.configSchema,
+        request.config,
+        `container driver '${request.name}'`,
+      ),
+    );
+    for (const event of ["interrupt", "progress", "done", "error"] as const) {
+      driver.on(
+        event,
+        (value) =>
+          new Promise<void>((resolve) => {
+            const id = ++eventId;
+            acknowledgements.set(id, resolve);
+            writeMessage(process.stdout, { id, event, value });
+          }),
+      );
+    }
+    await mkdir("/tmp/lux-run", { recursive: true });
+    await mkdir("/tmp/lux-runs", { recursive: true });
+    return driver.start({
+      ...request.context,
+      isolatedHome: "/home/lux",
+      abortSignal: abort.signal,
+    });
+  }
+  if (!driver) throw new Error("container driver has not started");
+  switch (message.method) {
+    case "respond":
+      return driver.respond(AnswerSchema.parse(message.value));
+    case "quiesce":
+      return driver.quiesce?.();
+    case "collect":
+      return driver.collect();
+    case "close":
+      return driver.close();
+    default:
+      throw new Error("unknown container RPC method");
+  }
+};
+readMessages(
+  process.stdin,
+  (message) => {
+    if (message.ack) {
+      acknowledgements.get(message.id)?.();
+      acknowledgements.delete(message.id);
+      return;
+    }
+    void dispatch(message).then(
+      (value) => writeMessage(process.stdout, { id: message.id, value }),
+      (error: unknown) =>
+        writeMessage(process.stdout, {
+          id: message.id,
+          error: error instanceof Error ? error.message : String(error),
+        }),
+    );
+  },
+  () => {
+    abort.abort();
+    process.exitCode = 1;
+    process.stdin.destroy();
+  },
+);
+process.stdin.on("end", () => {
+  abort.abort();
+  for (const resolve of acknowledgements.values()) resolve();
+  void driver?.close().finally(() => {
+    process.exitCode = 0;
+  });
+});
+process.stdout.on("error", () => {
+  abort.abort();
+  process.exitCode = 1;
+});

package/src/core/case.ts

@@ -2,6 +2,7 @@ import { z } from "zod";
 import type { AssertionPlugin } from "./assertion.js";
 import { collectEvalCaseExtensions, setEvalCaseExtensions } from "./case-authoring-state.js";
 import { DriverCapabilitySchema } from "./driver.js";
+import { DriverExecutionSchema } from "./driver-execution.js";
 import { EvaluationMetadataSchema } from "./evaluation-clusters.js";
 import { HarnessMatrixSchema } from "./harness-matrix.js";
 import type { LifecycleHooksPlugin } from "./lifecycle-hooks.js";
@@ -20,7 +21,13 @@ export type FixturesRef = z.infer<typeof FixturesRefSchema>;
 // `defineEvalCase` discriminate the config type on `name`.
 export const DriverRefSchema = z.union([
   z.string(),
-  z.object({ name: z.string(), config: z.unknown().optional() }).strict(),
+  z
+    .object({
+      name: z.string(),
+      config: z.unknown().optional(),
+      execution: DriverExecutionSchema.optional(),
+    })
+    .strict(),
 ]);
 export type DriverRef = z.infer<typeof DriverRefSchema>;
 

package/src/core/driver-execution.ts

@@ -0,0 +1,84 @@
+import { z } from "zod";
+
+const homePath = z
+  .string()
+  .min(1)
+  .refine(
+    (value) =>
+      !value.startsWith("/") &&
+      !value.includes("\\") &&
+      value.split("/").every((part) => part !== ".." && part !== "." && part !== ""),
+    "must be a relative path within the container home",
+  );
+
+export const ContainerExecutionSchema = z
+  .object({
+    kind: z.literal("container"),
+    /** A locally available image containing Lux and the selected Linux harness. */
+    image: z.string().min(1),
+    command: z.string().min(1).optional(),
+    /** The worker shipped with the same Lux build as the host. */
+    worker: z.string().min(1).optional(),
+    /** Optional module in the image exporting a custom DriverPlugin as default. */
+    driverModule: z.string().min(1).optional(),
+    mounts: z
+      .array(
+        z
+          .object({
+            source: z.string().min(1),
+            target: z.string().min(1).optional(),
+            readOnly: z.boolean().optional(),
+          })
+          .strict(),
+      )
+      .optional(),
+    /** Only these host environment variables enter the container. */
+    passEnv: z.array(z.string().regex(/^[A-Za-z_][A-Za-z0-9_]*$/)).optional(),
+    env: z.record(z.string().regex(/^[A-Za-z_][A-Za-z0-9_]*$/), z.string()).optional(),
+    /** Private copies, never host-home mounts; deleted after the run. */
+    homeFiles: z
+      .array(
+        z
+          .object({
+            destination: homePath,
+            source: z.discriminatedUnion("kind", [
+              z.object({ kind: z.literal("file"), path: z.string().min(1) }).strict(),
+              z
+                .object({
+                  kind: z.literal("keychain"),
+                  service: z.string().min(1),
+                  account: z.string().min(1),
+                  encoding: z.enum(["utf8", "go-keyring-base64"]).optional(),
+                })
+                .strict(),
+            ]),
+          })
+          .strict(),
+      )
+      .max(32)
+      .optional(),
+    network: z.enum(["bridge", "none"]).optional(),
+    user: z.string().min(1).optional(),
+    memory: z
+      .string()
+      .regex(/^[1-9][0-9]*[bkmgt]?$/i)
+      .optional(),
+    cpus: z.number().positive().optional(),
+    pidsLimit: z.number().int().positive().optional(),
+    startupTimeoutMs: z.number().int().positive().optional(),
+  })
+  .strict();
+
+export const DriverExecutionSchema = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("host") }).strict(),
+  ContainerExecutionSchema,
+]);
+export type DriverExecution = z.infer<typeof DriverExecutionSchema>;
+export type ContainerExecution = z.infer<typeof ContainerExecutionSchema>;
+
+export const driverExecutionOf = (reference: unknown): DriverExecution | undefined => {
+  if (!reference || typeof reference !== "object" || !("execution" in reference)) return undefined;
+  return reference.execution === undefined
+    ? undefined
+    : DriverExecutionSchema.parse(reference.execution);
+};

package/src/core/driver.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import type { DriverExecution } from "./driver-execution.js";
 import type { EventHandler } from "./emitter.js";
 import type { Answer, Done, ErrorEvent, Interrupt, Progress, ReadyState } from "./events.js";
 import type { ReasoningEffort } from "./harness-catalog.js";
@@ -28,6 +29,8 @@ export type ResolvedFixtures = z.infer<typeof ResolvedFixturesSchema>;
 export type StartContext = {
   /** Stable selected case id, available to drivers that multiplex scenarios. */
   caseId?: string;
+  /** Private home owned by an outer execution boundary; never the caller’s home. */
+  isolatedHome?: string;
   prompt: string;
   fixtures?: ResolvedFixtures | undefined;
   /** Authored fixture values selected for this case. */
@@ -139,4 +142,9 @@ export const defineDriver = <S extends z.ZodType>(
 export const driverRef = <S extends z.ZodType>(
   plugin: { name: string; configSchema: S },
   config: z.input<S>,
-): { name: string; config: z.input<S> } => ({ name: plugin.name, config });
+  execution?: DriverExecution,
+): { name: string; config: z.input<S>; execution?: DriverExecution } => ({
+  name: plugin.name,
+  config,
+  ...(execution ? { execution } : {}),
+});

package/src/core/harness-catalogs/cursor.ts

@@ -4,7 +4,7 @@ export const cursorCatalog = defineHarnessCatalog({
   driver: "cursor",
   verified: "2026-09-18",
   sources: [
-    "agent --list-models (account-scoped, needs a login)",
+    "cursor-agent --list-models (account-scoped, needs a login)",
     "https://cursor.com/docs/models",
     "https://cursor.com/docs/cli/acp",
   ],