@prismatic-io/lux 0.0.1

package/src/drivers/mcp/index.ts

@@ -0,0 +1,351 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { getDefaultEnvironment } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { z } from "zod";
+import {
+  type AgentDriver,
+  type Answer,
+  type Artifact,
+  type DriverEventMap,
+  type DriverPlugin,
+  type ListedTool,
+  MCP_INIT_KIND,
+  MCP_TOOLS_LIST_KIND,
+  type McpInitPayload,
+  type Progress,
+  type ReadyState,
+  type StartContext,
+  TOOL_CALL_KIND,
+  TOOL_RESULT_KIND,
+  type ToolResultPayload,
+  TypedEmitter,
+} from "../../core/index.js";
+import { McpStdioClientTransport } from "./transport.js";
+
+/**
+ * A single probe step. The driver speaks MCP directly — no LLM — so a "prompt"
+ * has no meaning here; the *probe* is the script. `list-tools` captures the
+ * `tools/list` surface; `call` invokes one tool and captures its result.
+ */
+const ProbeStepSchema = z.discriminatedUnion("op", [
+  z.object({ op: z.literal("list-tools") }).strict(),
+  z
+    .object({
+      op: z.literal("call"),
+      tool: z.string(),
+      args: z.record(z.string(), z.unknown()).default({}),
+    })
+    .strict(),
+]);
+export type ProbeStep = z.infer<typeof ProbeStepSchema>;
+
+/**
+ * Deterministic, no-LLM driver that spawns a local MCP server over stdio,
+ * runs the `initialize`/`tools/list`/`tools/call` handshake, and maps the
+ * protocol onto Lux's event model: `tool-call` (shared kind, so `tool-called*`
+ * assertions work), `tool-result` (the result the server returned), plus
+ * `mcp-init` and `mcp-tools-list` protocol captures. A tool that returns
+ * `isError: true` is a normal, gradable result; only a protocol/transport
+ * failure ends the run as a driver `error`. This is the flake-free tier where
+ * `--loop` pass^k is meaningful, and the code-free way to wrap any local
+ * stdio MCP server in evals.
+ */
+export const McpProbeDriverConfigSchema = z
+  .object({
+    /** Executable to spawn the server (e.g. "node", "npx"). */
+    command: z.string(),
+    /**
+     * Args to the server. `${ARTIFACTS_DIR}` and `${RUN_DIR}` are expanded per
+     * run — e.g. pass `${ARTIFACTS_DIR}` as a server's working-directory arg.
+     */
+    args: z.array(z.string()).default([]),
+    /** Working directory of the server process. Defaults to the run's artifacts dir. */
+    cwd: z.string().optional(),
+    /** Extra env for the server. Values also expand `${ARTIFACTS_DIR}`/`${RUN_DIR}`. */
+    env: z.record(z.string(), z.string()).optional(),
+    /**
+     * Names of variables to forward from the harness env into the server. The
+     * SDK stdio transport otherwise inherits only a safe allowlist, so secrets
+     * like PRISM_REFRESH_TOKEN must be named here — by NAME, never frozen into
+     * the case.
+     */
+    inheritEnv: z.array(z.string()).optional(),
+    /** The steps to run. Defaults to a single `tools/list` capture. */
+    probe: z.array(ProbeStepSchema).default([{ op: "list-tools" }]),
+    /** Timeout for the initialize handshake. */
+    startupTimeoutMs: z.number().positive().default(30_000),
+    /** Timeout for each `tools/list` / `tools/call` request. */
+    stepTimeoutMs: z.number().positive().default(60_000),
+    /** Safety cap for a paginated `tools/list` operation. */
+    maxListPages: z.number().int().positive().default(100),
+  })
+  .strict();
+export type McpProbeDriverConfig = z.infer<typeof McpProbeDriverConfigSchema>;
+
+const ARTIFACTS_DIR_PLACEHOLDER = `\${ARTIFACTS_DIR}`;
+const RUN_DIR_PLACEHOLDER = `\${RUN_DIR}`;
+let stderrWritable = true;
+
+const writeServerStderr = (line: string): void => {
+  if (!stderrWritable) return;
+  stderrWritable = process.stderr.write(`[mcp-server] ${line}\n`);
+  if (!stderrWritable) {
+    process.stderr.once("drain", () => {
+      stderrWritable = true;
+    });
+  }
+};
+
+/** Expand the per-run path placeholders a case may embed in args/env/cwd. */
+export const expandPlaceholders = (
+  value: string,
+  ctx: { runDir: string; artifactsDir: string },
+): string =>
+  value
+    .replaceAll(ARTIFACTS_DIR_PLACEHOLDER, ctx.artifactsDir)
+    .replaceAll(RUN_DIR_PLACEHOLDER, ctx.runDir);
+
+/** Concatenate the text blocks of an MCP result's content, for substring checks. */
+const flattenTextContent = (content: unknown): string => {
+  if (!Array.isArray(content)) return "";
+  return content
+    .filter(
+      (b): b is { type: "text"; text: string } =>
+        typeof b === "object" &&
+        b !== null &&
+        (b as { type?: unknown }).type === "text" &&
+        typeof (b as { text?: unknown }).text === "string",
+    )
+    .map((b) => b.text)
+    .join("\n");
+};
+
+/** Project an SDK `CallToolResult` (either the modern or legacy shape) onto Lux's `ToolResultPayload`. */
+const toToolResultPayload = (
+  name: string,
+  toolUseId: string,
+  result: unknown,
+  durationMs: number,
+): ToolResultPayload => {
+  const r = (typeof result === "object" && result !== null ? result : {}) as {
+    content?: unknown;
+    structuredContent?: unknown;
+    isError?: unknown;
+  };
+  const structured = r.structuredContent;
+  return {
+    name,
+    toolUseId,
+    content: r.content ?? [],
+    ...(structured !== null && typeof structured === "object"
+      ? { structuredContent: structured as Record<string, unknown> }
+      : {}),
+    isError: r.isError === true,
+    text: flattenTextContent(r.content),
+    durationMs,
+  };
+};
+
+const buildServerEnv = (
+  config: McpProbeDriverConfig,
+  expand: (s: string) => string,
+): Record<string, string> => {
+  const env: Record<string, string> = { ...getDefaultEnvironment() };
+  for (const name of config.inheritEnv ?? []) {
+    const value = process.env[name];
+    if (value !== undefined) env[name] = value;
+  }
+  for (const [key, value] of Object.entries(config.env ?? {})) env[key] = expand(value);
+  return env;
+};
+
+class McpProbeDriverImpl implements AgentDriver {
+  private readonly emitter = new TypedEmitter<DriverEventMap>();
+  private readonly config: McpProbeDriverConfig;
+  private client: Client | null = null;
+  private transport: McpStdioClientTransport | null = null;
+  private seq = 0;
+  private closePromise: Promise<void> | null = null;
+  private terminalSent = false;
+  private onAbort: (() => void) | null = null;
+  private abortSignal: AbortSignal | null = null;
+
+  constructor(config: McpProbeDriverConfig) {
+    this.config = config;
+  }
+
+  on<K extends keyof DriverEventMap>(event: K, handler: (e: DriverEventMap[K]) => void): void {
+    this.emitter.on(event, handler);
+  }
+
+  off<K extends keyof DriverEventMap>(event: K, handler: (e: DriverEventMap[K]) => void): void {
+    this.emitter.off(event, handler);
+  }
+
+  private progress(kind: string, payload: unknown): Progress {
+    return { id: `mcp-${this.seq++}`, kind, payload, ts: Date.now() };
+  }
+
+  async start(ctx: StartContext): Promise<ReadyState> {
+    const expand = (s: string): string => expandPlaceholders(s, ctx);
+    const args = this.config.args.map(expand);
+    const cwd = this.config.cwd ? expand(this.config.cwd) : ctx.artifactsDir;
+    const env = buildServerEnv(this.config, expand);
+
+    this.abortSignal = ctx.abortSignal;
+    this.onAbort = () => void this.close();
+    if (ctx.abortSignal.aborted) {
+      throw new Error("mcp-probe driver: aborted before start");
+    }
+    ctx.abortSignal.addEventListener("abort", this.onAbort, { once: true });
+
+    const transport = new McpStdioClientTransport({
+      command: this.config.command,
+      args,
+      env,
+      cwd,
+      writeStderr: writeServerStderr,
+    });
+    const client = new Client({ name: "lux-mcp-probe", version: "1.0.0" });
+    this.transport = transport;
+    this.client = client;
+
+    try {
+      await client.connect(transport, {
+        timeout: this.config.startupTimeoutMs,
+        maxTotalTimeout: this.config.startupTimeoutMs,
+        signal: ctx.abortSignal,
+      });
+    } catch (err) {
+      await this.close();
+      const failure = transport.failure ?? err;
+      throw new Error(
+        `mcp-probe driver: ${failure instanceof Error ? failure.message : String(failure)}`,
+      );
+    }
+
+    const serverInfo = client.getServerVersion();
+    const capabilities = client.getServerCapabilities();
+    const instructions = client.getInstructions();
+    const init: McpInitPayload = {
+      ...(serverInfo ? { serverInfo: { name: serverInfo.name, version: serverInfo.version } } : {}),
+      ...(capabilities ? { capabilities: capabilities as Record<string, unknown> } : {}),
+      ...(instructions ? { instructions } : {}),
+    };
+
+    // Probe after start() resolves so the orchestrator records `ready` first.
+    setImmediate(() => void this.runProbe(init));
+
+    return {
+      agentId: "mcp-probe",
+      detail: {
+        command: this.config.command,
+        ...(serverInfo?.version ? { serverVersion: serverInfo.version } : {}),
+      },
+    };
+  }
+
+  private async runProbe(init: McpInitPayload): Promise<void> {
+    const client = this.client;
+    if (!client) return;
+    try {
+      await this.emitter.emit("progress", this.progress(MCP_INIT_KIND, init));
+
+      for (const step of this.config.probe) {
+        if (this.terminalSent) return;
+        if (step.op === "list-tools") {
+          const tools: ListedTool[] = [];
+          const seenCursors = new Set<string>();
+          let cursor: string | undefined;
+          for (let page = 1; ; page++) {
+            if (page > this.config.maxListPages) {
+              throw new Error(`tools/list exceeded ${this.config.maxListPages} pages`);
+            }
+            const result = await client.listTools(cursor ? { cursor } : undefined, {
+              timeout: this.config.stepTimeoutMs,
+              maxTotalTimeout: this.config.stepTimeoutMs,
+              ...(this.abortSignal ? { signal: this.abortSignal } : {}),
+            });
+            tools.push(...(result.tools as ListedTool[]));
+            cursor = result.nextCursor;
+            if (!cursor) break;
+            if (seenCursors.has(cursor)) {
+              throw new Error(`tools/list repeated cursor '${cursor}'`);
+            }
+            seenCursors.add(cursor);
+          }
+          await this.emitter.emit("progress", this.progress(MCP_TOOLS_LIST_KIND, { tools }));
+        } else {
+          const toolUseId = `probe-${this.seq}`;
+          await this.emitter.emit(
+            "progress",
+            this.progress(TOOL_CALL_KIND, { name: step.tool, input: step.args, toolUseId }),
+          );
+          const startedAt = Date.now();
+          const result = await client.callTool(
+            { name: step.tool, arguments: step.args },
+            undefined,
+            {
+              timeout: this.config.stepTimeoutMs,
+              maxTotalTimeout: this.config.stepTimeoutMs,
+              ...(this.abortSignal ? { signal: this.abortSignal } : {}),
+            },
+          );
+          await this.emitter.emit(
+            "progress",
+            this.progress(
+              TOOL_RESULT_KIND,
+              toToolResultPayload(step.tool, toolUseId, result, Date.now() - startedAt),
+            ),
+          );
+        }
+      }
+
+      if (this.terminalSent) return;
+      this.terminalSent = true;
+      await this.emitter.emit("done", {
+        exitReason: "done",
+        summary: { serverInfo: init.serverInfo },
+      });
+    } catch (err) {
+      if (this.terminalSent) return;
+      this.terminalSent = true;
+      const failure = this.transport?.failure ?? err;
+      await this.emitter.emit("error", {
+        exitReason: "error",
+        reason: failure instanceof Error ? failure.message : String(failure),
+      });
+    }
+  }
+
+  async respond(_answer: Answer): Promise<void> {
+    throw new Error("mcp-probe driver does not support interrupts");
+  }
+
+  async collect(): Promise<Artifact[]> {
+    return [];
+  }
+
+  quiesce(): Promise<void> {
+    return this.close();
+  }
+
+  close(): Promise<void> {
+    this.closePromise ??= this.closeResources();
+    return this.closePromise;
+  }
+
+  private async closeResources(): Promise<void> {
+    if (this.onAbort && this.abortSignal) {
+      this.abortSignal.removeEventListener("abort", this.onAbort);
+    }
+    await this.client?.close().catch(() => {});
+    await this.transport?.close().catch(() => {});
+    this.emitter.removeAllListeners();
+  }
+}
+
+export const mcpProbeDriver: DriverPlugin<McpProbeDriverConfig> = {
+  name: "mcp-probe",
+  configSchema: McpProbeDriverConfigSchema,
+  create: (config) => new McpProbeDriverImpl(config),
+};

package/src/drivers/mcp/transport.ts

@@ -0,0 +1,222 @@
+import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
+import type { JSONRPCMessage } from "@modelcontextprotocol/sdk/types.js";
+import { JSONRPCMessageSchema } from "@modelcontextprotocol/sdk/types.js";
+import { type ManagedProcess, spawnManagedProcess } from "../../core/index.js";
+
+const DEFAULT_MAX_PROTOCOL_LINE_BYTES = 10_000_000;
+const DEFAULT_MAX_STDERR_TAIL_CHARS = 8_192;
+const DEFAULT_KILL_GRACE_MS = 5_000;
+
+export type McpStdioTransportOptions = {
+  command: string;
+  args?: string[];
+  cwd?: string;
+  env?: NodeJS.ProcessEnv;
+  killGraceMs?: number;
+  maxProtocolLineBytes?: number;
+  maxStderrTailChars?: number;
+  writeStderr?: (line: string) => void;
+};
+
+/**
+ * MCP's stdio framing with Lux-owned process-group and memory boundaries.
+ * Protocol messages remain SDK-validated, but no SDK process lifecycle leaks
+ * through this transport.
+ */
+export class McpStdioClientTransport implements Transport {
+  onclose?: () => void;
+  onerror?: (error: Error) => void;
+  onmessage?: (message: JSONRPCMessage) => void;
+
+  private readonly options: McpStdioTransportOptions;
+  private readonly maxProtocolLineBytes: number;
+  private readonly maxStderrTailChars: number;
+  private process: ManagedProcess | null = null;
+  private stdoutChunks: Buffer[] = [];
+  private stdoutBytes = 0;
+  private stderrTail = "";
+  private stderrTruncated = false;
+  private closePromise: Promise<void> | null = null;
+  private closeNotified = false;
+  private started = false;
+  private closing = false;
+  private transportError: Error | null = null;
+
+  constructor(options: McpStdioTransportOptions) {
+    this.options = options;
+    this.maxProtocolLineBytes = options.maxProtocolLineBytes ?? DEFAULT_MAX_PROTOCOL_LINE_BYTES;
+    this.maxStderrTailChars = options.maxStderrTailChars ?? DEFAULT_MAX_STDERR_TAIL_CHARS;
+  }
+
+  get failure(): Error | null {
+    return this.transportError;
+  }
+
+  get pid(): number | null {
+    return this.process?.child.pid ?? null;
+  }
+
+  async start(): Promise<void> {
+    if (this.started) throw new Error("MCP stdio transport already started");
+    this.started = true;
+
+    const managed = spawnManagedProcess(this.options.command, this.options.args ?? [], {
+      killGraceMs: this.options.killGraceMs ?? DEFAULT_KILL_GRACE_MS,
+      ...(this.options.cwd === undefined ? {} : { cwd: this.options.cwd }),
+      ...(this.options.env === undefined ? {} : { env: this.options.env }),
+    });
+    this.process = managed;
+    const { child } = managed;
+
+    child.stdout.on("data", (chunk: Buffer) => this.readStdout(chunk));
+    child.stdout.on("end", () => {
+      if (!this.closing && this.stdoutBytes > 0) {
+        this.fail(
+          new Error(
+            `MCP server stdout ended with an unterminated ${this.stdoutBytes}-byte protocol line`,
+          ),
+        );
+      }
+      this.clearStdout();
+    });
+    child.stdout.on("error", (err) => this.fail(new Error(`MCP server stdout: ${err.message}`)));
+
+    child.stderr.setEncoding("utf8");
+    child.stderr.on("data", (chunk: string) => this.readStderr(chunk));
+    child.stderr.on("end", () => this.flushStderr());
+    child.stderr.on("error", (err) => this.fail(new Error(`MCP server stderr: ${err.message}`)));
+
+    void managed.exited.then(() => {
+      this.flushStderr();
+      this.clearStdout();
+      this.process = null;
+      this.notifyClose();
+    });
+
+    try {
+      await managed.spawned;
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      this.transportError ??= error;
+      await managed.terminate();
+      throw error;
+    }
+  }
+
+  async send(message: JSONRPCMessage): Promise<void> {
+    const stdin = this.process?.child.stdin;
+    if (!stdin || this.closing || stdin.destroyed) throw new Error("MCP stdio transport is closed");
+    const serialized = `${JSON.stringify(message)}\n`;
+    await new Promise<void>((resolve, reject) => {
+      stdin.write(serialized, (err) => {
+        if (err) reject(new Error(`MCP server stdin: ${err.message}`, { cause: err }));
+        else resolve();
+      });
+    });
+  }
+
+  close(): Promise<void> {
+    if (this.closePromise) return this.closePromise;
+    this.closing = true;
+    this.closePromise = (async () => {
+      const managed = this.process;
+      if (managed) {
+        managed.child.stdin.end();
+        await managed.terminate();
+      }
+      this.clearStdout();
+      this.flushStderr();
+      this.notifyClose();
+    })();
+    return this.closePromise;
+  }
+
+  private readStdout(chunk: Buffer): void {
+    if (this.transportError || this.closing) return;
+    let offset = 0;
+    while (offset < chunk.length) {
+      const newline = chunk.indexOf(0x0a, offset);
+      const end = newline === -1 ? chunk.length : newline;
+      const segment = chunk.subarray(offset, end);
+      const lineBytes = this.stdoutBytes + segment.length;
+      if (lineBytes > this.maxProtocolLineBytes) {
+        this.fail(
+          new Error(`MCP server stdout protocol line exceeded ${this.maxProtocolLineBytes} bytes`),
+        );
+        return;
+      }
+      if (segment.length > 0) {
+        this.stdoutChunks.push(segment);
+        this.stdoutBytes = lineBytes;
+      }
+      if (newline === -1) return;
+      this.dispatchLine(Buffer.concat(this.stdoutChunks, this.stdoutBytes));
+      if (this.transportError) return;
+      this.clearStdout();
+      offset = newline + 1;
+    }
+  }
+
+  private clearStdout(): void {
+    this.stdoutChunks = [];
+    this.stdoutBytes = 0;
+  }
+
+  private dispatchLine(lineBuffer: Buffer): void {
+    const line = lineBuffer.toString("utf8").replace(/\r$/, "");
+    try {
+      const message = JSONRPCMessageSchema.parse(JSON.parse(line));
+      this.onmessage?.(message);
+    } catch (err) {
+      this.fail(
+        new Error(
+          `MCP server emitted an invalid JSON-RPC line: ${
+            err instanceof Error ? err.message : String(err)
+          }`,
+          { cause: err },
+        ),
+      );
+    }
+  }
+
+  private readStderr(chunk: string): void {
+    let offset = 0;
+    while (offset < chunk.length) {
+      const newline = chunk.indexOf("\n", offset);
+      const end = newline === -1 ? chunk.length : newline;
+      this.appendStderr(chunk.slice(offset, end));
+      if (newline === -1) return;
+      this.flushStderr();
+      offset = newline + 1;
+    }
+  }
+
+  private appendStderr(text: string): void {
+    if (text.length === 0) return;
+    if (this.stderrTail.length + text.length > this.maxStderrTailChars) {
+      this.stderrTruncated = true;
+    }
+    this.stderrTail = `${this.stderrTail}${text}`.slice(-this.maxStderrTailChars);
+  }
+
+  private flushStderr(): void {
+    if (!this.stderrTail && !this.stderrTruncated) return;
+    const line = this.stderrTail.replace(/\r$/, "");
+    this.options.writeStderr?.(this.stderrTruncated ? `[truncated] …${line}` : line);
+    this.stderrTail = "";
+    this.stderrTruncated = false;
+  }
+
+  private fail(error: Error): void {
+    if (this.transportError || this.closing) return;
+    this.transportError = error;
+    this.onerror?.(error);
+    void this.close();
+  }
+
+  private notifyClose(): void {
+    if (this.closeNotified) return;
+    this.closeNotified = true;
+    this.onclose?.();
+  }
+}

package/src/drivers/shared/artifacts.ts

@@ -0,0 +1,86 @@
+import { lstat, readdir, realpath } from "node:fs/promises";
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
+import {
+  ARTIFACT_SNAPSHOT_MANIFEST,
+  type Artifact,
+  readArtifactSnapshotManifest,
+} from "../../core/index.js";
+
+const IGNORED_DIRS = new Set(["node_modules", "lib", "dist"]);
+
+/** Enumerate agent-authored files without following symlinks or build/dependency trees. */
+export const walkArtifacts = async (root: string, max = 500): Promise<Artifact[]> => {
+  if (!Number.isSafeInteger(max) || max <= 0) {
+    throw new RangeError("artifact collection max must be a positive safe integer");
+  }
+  const requestedRoot = resolve(root);
+  const rootMetadata = await lstat(requestedRoot);
+  if (!rootMetadata.isDirectory() || rootMetadata.isSymbolicLink()) {
+    throw new Error(`artifact root must be a real directory: ${root}`);
+  }
+  const canonicalRoot = await realpath(requestedRoot);
+  const out: Artifact[] = [];
+  const addArtifact = (path: string, size: number): void => {
+    if (out.length >= max) {
+      throw new Error(`artifact collection exceeds ${max} files: ${root}`);
+    }
+    out.push({ path, size });
+  };
+  const collectSnapshot = async (dir: string): Promise<boolean> => {
+    const manifest = await readArtifactSnapshotManifest(dir);
+    if (!manifest) return false;
+    if (manifest.name !== basename(dir)) {
+      throw new Error(
+        `artifact snapshot manifest names ${manifest.name}, expected ${basename(dir)}`,
+      );
+    }
+    const canonicalSnapshotRoot = await realpath(dir);
+    for (const file of manifest.files) {
+      const full = resolve(dir, file.path);
+      const canonicalParent = await realpath(dirname(full));
+      if (
+        canonicalParent !== canonicalSnapshotRoot &&
+        !canonicalParent.startsWith(`${canonicalSnapshotRoot}${sep}`)
+      ) {
+        throw new Error(`artifact snapshot path resolves outside its root: ${file.path}`);
+      }
+      const metadata = await lstat(full);
+      if (metadata.isSymbolicLink() || !metadata.isFile() || metadata.size !== file.bytes) {
+        throw new Error(`artifact snapshot file does not match its manifest: ${file.path}`);
+      }
+      addArtifact(relative(requestedRoot, full).split(sep).join("/"), metadata.size);
+    }
+    const manifestPath = join(dir, ARTIFACT_SNAPSHOT_MANIFEST);
+    const manifestStats = await lstat(manifestPath);
+    addArtifact(relative(requestedRoot, manifestPath).split(sep).join("/"), manifestStats.size);
+    return true;
+  };
+  const walk = async (dir: string): Promise<void> => {
+    const canonicalDirectory = await realpath(dir);
+    if (
+      canonicalDirectory !== canonicalRoot &&
+      !canonicalDirectory.startsWith(`${canonicalRoot}${sep}`)
+    ) {
+      throw new Error(`artifact directory resolves outside its root: ${dir}`);
+    }
+    if (await collectSnapshot(dir)) return;
+    const entries = await readdir(dir, { withFileTypes: true });
+    entries.sort((a, b) => a.name.localeCompare(b.name));
+    for (const entry of entries) {
+      if (entry.isSymbolicLink()) continue;
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (await collectSnapshot(full)) continue;
+        if (entry.name.startsWith(".") || IGNORED_DIRS.has(entry.name)) continue;
+        await walk(full);
+      } else if (entry.isFile()) {
+        const metadata = await lstat(full);
+        if (metadata.isFile()) {
+          addArtifact(relative(requestedRoot, full).split(sep).join("/"), metadata.size);
+        }
+      }
+    }
+  };
+  await walk(requestedRoot);
+  return out;
+};

package/src/drivers/shared/secure-copy.ts

@@ -0,0 +1,40 @@
+import { constants, lstat, open, realpath, stat } from "node:fs/promises";
+import { resolve, sep } from "node:path";
+
+const isWithin = (parent: string, child: string): boolean => {
+  const root = resolve(parent);
+  const path = resolve(child);
+  return path === root || path.startsWith(`${root}${sep}`);
+};
+
+export const copyRegularFileNoFollow = async (
+  sourceRoot: string,
+  sourcePath: string,
+  targetPath: string,
+): Promise<void> => {
+  if ((await lstat(sourcePath)).isSymbolicLink()) {
+    throw new Error(`artifact cannot be a symlink: ${sourcePath}`);
+  }
+  const source = await open(sourcePath, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+  let target: Awaited<ReturnType<typeof open>> | undefined;
+  try {
+    const sourceStat = await source.stat();
+    if (!sourceStat.isFile()) throw new Error(`artifact is not a regular file: ${sourcePath}`);
+    const resolvedSource = await realpath(sourcePath);
+    if (!isWithin(sourceRoot, resolvedSource)) {
+      throw new Error(`artifact resolves outside the isolated workspace: ${sourcePath}`);
+    }
+    const resolvedStat = await stat(resolvedSource);
+    if (
+      !resolvedStat.isFile() ||
+      resolvedStat.dev !== sourceStat.dev ||
+      resolvedStat.ino !== sourceStat.ino
+    ) {
+      throw new Error(`artifact changed while being collected: ${sourcePath}`);
+    }
+    target = await open(targetPath, "wx", sourceStat.mode & 0o777);
+    await target.writeFile(source.createReadStream({ autoClose: false }));
+  } finally {
+    await Promise.allSettled([source.close(), ...(target ? [target.close()] : [])]);
+  }
+};