@prismatic-io/lux 0.0.2-preview.3 → 0.0.2-preview.32

package/src/drivers/shared/acp-transport.ts

@@ -0,0 +1,187 @@
+import { type ManagedProcess, spawnManagedProcess } from "../../core/index.js";
+
+export type RpcRecord = Record<string, unknown>;
+export type RpcId = number | string;
+export const asRecord = (value: unknown): RpcRecord | undefined =>
+  value !== null && typeof value === "object" && !Array.isArray(value)
+    ? (value as RpcRecord)
+    : undefined;
+
+type TransportOptions = {
+  /** Harness name used in failure messages. */
+  label: string;
+  command: string;
+  args: string[];
+  cwd: string;
+  env?: NodeJS.ProcessEnv;
+  signal: AbortSignal;
+  maxLineBytes: number;
+  maxQueuedBytes: number;
+  onMessage: (message: RpcRecord) => Promise<void>;
+  onFailure: (error: Error) => void;
+  onActivity: () => void;
+};
+
+export class AcpTransport {
+  private readonly process: ManagedProcess;
+  private readonly pending = new Map<
+    RpcId,
+    {
+      resolve: (result: RpcRecord) => void;
+      reject: (error: Error) => void;
+      timer: NodeJS.Timeout | undefined;
+    }
+  >();
+  private nextId = 1;
+  private buffer = Buffer.alloc(0);
+  private queuedBytes = 0;
+  private chain: Promise<void> = Promise.resolve();
+  private stopped = false;
+  private stderrTail = "";
+
+  private readonly options: TransportOptions;
+
+  constructor(options: TransportOptions) {
+    this.options = options;
+    this.process = spawnManagedProcess(options.command, options.args, {
+      cwd: options.cwd,
+      ...(options.env ? { env: options.env } : {}),
+      signal: options.signal,
+    });
+    this.process.child.stdout.on("data", (chunk: Buffer) => this.read(chunk));
+    this.process.child.stderr.setEncoding("utf8");
+    this.process.child.stderr.on("data", (chunk: string) => {
+      this.stderrTail = (this.stderrTail + chunk).slice(-8_192);
+    });
+    void this.process.exited.then(({ exitCode, signal }) => {
+      if (!this.stopped)
+        this.fail(
+          new Error(
+            `${this.options.label} exited before completion (code=${exitCode}, signal=${signal})${this.stderrTail ? `: ${this.stderrTail}` : ""}`,
+          ),
+        );
+    });
+  }
+
+  async spawned(): Promise<void> {
+    await this.process.spawned;
+  }
+
+  request(method: string, params: RpcRecord, timeoutMs?: number): Promise<RpcRecord> {
+    if (this.stopped) return Promise.reject(new Error(`${this.options.label} is closed`));
+    const id = this.nextId++;
+    return new Promise((resolve, reject) => {
+      const timer =
+        timeoutMs === undefined
+          ? undefined
+          : setTimeout(() => {
+              this.fail(
+                new Error(`${this.options.label} ${method} timed out after ${timeoutMs}ms`),
+              );
+            }, timeoutMs);
+      this.pending.set(id, { resolve, reject, timer });
+      try {
+        this.write({ id, method, params });
+      } catch (error) {
+        this.fail(error instanceof Error ? error : new Error(String(error)));
+      }
+    });
+  }
+
+  write(message: RpcRecord): void {
+    if (this.stopped) throw new Error(`${this.options.label} is closed`);
+    const line = `${JSON.stringify({ jsonrpc: "2.0", ...message })}\n`;
+    if (Buffer.byteLength(line) > this.options.maxLineBytes)
+      throw new Error(`${this.options.label} outgoing message exceeded maxLineBytes`);
+    this.process.child.stdin.write(line);
+  }
+
+  async drained(): Promise<void> {
+    await this.chain;
+  }
+
+  async close(): Promise<void> {
+    this.stopped = true;
+    this.rejectPending(new Error(`${this.options.label} is closed`));
+    this.buffer = Buffer.alloc(0);
+    await this.process.terminate();
+  }
+
+  private rejectPending(error: Error): void {
+    for (const pending of this.pending.values()) {
+      clearTimeout(pending.timer);
+      pending.reject(error);
+    }
+    this.pending.clear();
+  }
+
+  private fail(error: Error): void {
+    if (this.stopped) return;
+    this.stopped = true;
+    this.rejectPending(error);
+    this.options.onFailure(error);
+    void this.process.terminate();
+  }
+
+  private read(chunk: Buffer): void {
+    let offset = 0;
+    while (offset < chunk.length && !this.stopped) {
+      const newline = chunk.indexOf(0x0a, offset);
+      const end = newline === -1 ? chunk.length : newline;
+      const segment = chunk.subarray(offset, end);
+      if (this.buffer.length + segment.length > this.options.maxLineBytes) {
+        this.fail(new Error(`${this.options.label} stdout line exceeded maxLineBytes`));
+        return;
+      }
+      this.buffer = Buffer.concat([this.buffer, segment]);
+      if (newline === -1) return;
+      const line = this.buffer;
+      this.buffer = Buffer.alloc(0);
+      this.line(line);
+      offset = newline + 1;
+    }
+  }
+
+  private line(line: Buffer): void {
+    if (!line.toString("utf8").trim()) return;
+    let message: RpcRecord | undefined;
+    try {
+      message = asRecord(JSON.parse(line.toString("utf8")));
+    } catch {
+      /* Rejected below. */
+    }
+    if (message?.jsonrpc !== "2.0") {
+      this.fail(new Error(`${this.options.label} returned an invalid JSON-RPC message`));
+      return;
+    }
+    this.options.onActivity();
+    if (message.method === undefined) {
+      const pending = this.pending.get(message.id as RpcId);
+      if (!pending) return;
+      this.pending.delete(message.id as RpcId);
+      clearTimeout(pending.timer);
+      const error = asRecord(message.error);
+      if (error)
+        pending.reject(new Error(String(error.message ?? `${this.options.label} request failed`)));
+      else pending.resolve(asRecord(message.result) ?? {});
+      return;
+    }
+    this.queuedBytes += line.length;
+    if (this.queuedBytes > this.options.maxQueuedBytes) {
+      this.fail(new Error(`${this.options.label} pending events exceeded maxQueuedBytes`));
+      return;
+    }
+    const queued = message;
+    this.chain = this.chain
+      .then(async () => {
+        try {
+          if (!this.stopped) await this.options.onMessage(queued);
+        } finally {
+          this.queuedBytes -= line.length;
+        }
+      })
+      .catch((error: unknown) =>
+        this.fail(error instanceof Error ? error : new Error(String(error))),
+      );
+  }
+}

package/src/drivers/shared/artifacts.ts

@@ -6,7 +6,7 @@ import {
   readArtifactSnapshotManifest,
 } from "../../core/index.js";
 
-const IGNORED_DIRS = new Set(["node_modules", "lib", "dist"]);
+const IGNORED_DIRS = new Set(["node_modules", "dist"]);
 
 /** Enumerate agent-authored files without following symlinks or build/dependency trees. */
 export const walkArtifacts = async (root: string, max = 500): Promise<Artifact[]> => {
@@ -71,7 +71,11 @@ export const walkArtifacts = async (root: string, max = 500): Promise<Artifact[]
       const full = join(dir, entry.name);
       if (entry.isDirectory()) {
         if (await collectSnapshot(full)) continue;
-        if (entry.name.startsWith(".") || IGNORED_DIRS.has(entry.name)) continue;
+        if (
+          (entry.name.startsWith(".") && entry.name !== ".spectral") ||
+          IGNORED_DIRS.has(entry.name)
+        )
+          continue;
         await walk(full);
       } else if (entry.isFile()) {
         const metadata = await lstat(full);

package/src/drivers/shared/experiment-behavior.ts

@@ -0,0 +1,214 @@
+import { lstat, readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+import { z } from "zod";
+import { walkAuthoredFiles } from "../../core/file-tree.js";
+import { contentHash, valueHash } from "../../core/hash.js";
+import {
+  prepareClaudeExperimentConfig,
+  prepareCodexExperimentConfig,
+} from "./experiment-policy.js";
+
+const ClaudeSettingsFileSchema = z.looseObject({
+  enabledPlugins: z.record(z.string(), z.boolean()).optional(),
+});
+const ClaudeInstalledPluginRecordSchema = z.looseObject({
+  installPath: z.string(),
+});
+const ClaudeInstalledPluginsFileSchema = z.looseObject({
+  plugins: z.record(z.string(), z.array(ClaudeInstalledPluginRecordSchema)),
+});
+
+const optionalRegularFileHash = async (path: string): Promise<string | null> => {
+  try {
+    const info = await lstat(path);
+    if (info.isSymbolicLink() || !info.isFile()) {
+      throw new Error(`behavior-affecting settings must be a regular file: ${path}`);
+    }
+    return contentHash(await readFile(path));
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+    throw error;
+  }
+};
+
+const driverConfigRecord = (driver: unknown): Record<string, unknown> => {
+  if (!driver || typeof driver !== "object") return {};
+  const config = (driver as { config?: unknown }).config;
+  return config && typeof config === "object" ? (config as Record<string, unknown>) : {};
+};
+
+export const claudeConfigRoot = (driver: unknown): string => {
+  const config = driverConfigRecord(driver);
+  const env =
+    config.env && typeof config.env === "object"
+      ? (config.env as Record<string, unknown>)
+      : undefined;
+  const configured = env?.CLAUDE_CONFIG_DIR;
+  const root =
+    typeof configured === "string"
+      ? configured
+      : (process.env.CLAUDE_CONFIG_DIR ?? join(homedir(), ".claude"));
+  if (!isAbsolute(root)) {
+    throw new Error("CLAUDE_CONFIG_DIR must be absolute for reproducible experiment identity");
+  }
+  return resolve(root);
+};
+
+const hashBehaviorDirectory = async (
+  root: string,
+  label: string,
+): Promise<Array<{ path: string; hash: string }>> => {
+  try {
+    const info = await lstat(root);
+    if (info.isSymbolicLink() || !info.isDirectory()) {
+      throw new Error(`behavior-affecting Claude source must be a real directory: ${root}`);
+    }
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
+    throw error;
+  }
+  const paths = await walkAuthoredFiles(root);
+  if (paths.length > 5_000) {
+    throw new Error(`behavior-affecting Claude source '${label}' exceeds 5000 files`);
+  }
+  let bytes = 0;
+  const hashes: Array<{ path: string; hash: string }> = [];
+  for (const path of paths) {
+    const content = await readFile(join(root, path));
+    bytes += content.length;
+    if (bytes > 256 * 1024 * 1024) {
+      throw new Error(`behavior-affecting Claude source '${label}' exceeds 256 MiB`);
+    }
+    hashes.push({ path: `${label}/${path}`, hash: contentHash(content) });
+  }
+  return hashes;
+};
+
+/**
+ * Hash every intentionally loaded user behavior source without persisting its
+ * contents. This covers user instructions/rules/output styles and the exact
+ * installed contents of plugins enabled by settings.json.
+ */
+export const claudeUserBehaviorHash = async (configRoot: string): Promise<string | null> => {
+  const settingsPath = join(configRoot, "settings.json");
+  const settingsHash = await optionalRegularFileHash(settingsPath);
+  const sources: Array<{ path: string; hash: string }> = [];
+  if (settingsHash) sources.push({ path: "settings.json", hash: settingsHash });
+  const claudeMdHash = await optionalRegularFileHash(join(configRoot, "CLAUDE.md"));
+  if (claudeMdHash) sources.push({ path: "CLAUDE.md", hash: claudeMdHash });
+  for (const directory of ["rules", "output-styles", "agents", "commands", "skills"]) {
+    sources.push(...(await hashBehaviorDirectory(join(configRoot, directory), directory)));
+  }
+
+  let settings: unknown;
+  try {
+    const contents = await readFile(settingsPath, "utf8");
+    try {
+      settings = JSON.parse(contents);
+    } catch {
+      throw new Error("Claude settings.json contains invalid JSON");
+    }
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      settings = undefined;
+    } else {
+      throw error;
+    }
+  }
+  const parsedSettings = ClaudeSettingsFileSchema.safeParse(settings);
+  if (settings !== undefined && !parsedSettings.success) {
+    throw new Error("Claude settings.json has an invalid enabledPlugins map");
+  }
+  const enabledPlugins = parsedSettings.success ? parsedSettings.data.enabledPlugins : undefined;
+  const enabledIds = Object.entries(enabledPlugins ?? {})
+    .filter(([, value]) => value === true)
+    .map(([id]) => id)
+    .sort();
+  if (enabledIds.length > 0) {
+    const installedPath = join(configRoot, "plugins", "installed_plugins.json");
+    const installedHash = await optionalRegularFileHash(installedPath);
+    if (installedHash) {
+      sources.push({ path: "plugins/installed_plugins.json", hash: installedHash });
+    }
+    let installed: unknown;
+    try {
+      installed = JSON.parse(await readFile(installedPath, "utf8"));
+    } catch {
+      installed = undefined;
+    }
+    const parsedInstalled = ClaudeInstalledPluginsFileSchema.safeParse(installed);
+    if (!parsedInstalled.success) {
+      throw new Error("enabled Claude plugins have invalid installed metadata");
+    }
+    const plugins = parsedInstalled.data.plugins;
+    for (const id of enabledIds) {
+      const records = plugins[id];
+      if (!records || records.length === 0) {
+        throw new Error(`enabled Claude plugin '${id}' has no installed content to hash`);
+      }
+      for (const [index, record] of records.entries()) {
+        const installPath = record.installPath;
+        sources.push(
+          ...(await hashBehaviorDirectory(resolve(installPath), `plugins/enabled/${id}/${index}`)),
+        );
+      }
+    }
+  }
+  return sources.length === 0 ? null : valueHash(sources);
+};
+
+export const configuredClaudeSourceHashes = async (
+  driver: unknown,
+  baseRoot: string,
+  cache: Map<string, Promise<string>> = new Map(),
+): Promise<Array<{ kind: "plugin" | "read"; path: string; hash: string }>> => {
+  const name =
+    typeof driver === "string" ? driver : (driver as { name?: unknown } | undefined)?.name;
+  const driverCli = name === "claude-code" || name === "codex" ? { name } : undefined;
+  if (!driverCli) return [];
+  const config = driverConfigRecord(driver);
+  // This also rejects path-bearing extraArgs that would evade the source
+  // hashes below. Runtime applies the same guard before driver creation.
+  if (driverCli.name === "claude-code") prepareClaudeExperimentConfig(config);
+  else prepareCodexExperimentConfig(config);
+  const isolation =
+    config.isolation && typeof config.isolation === "object"
+      ? (config.isolation as Record<string, unknown>)
+      : undefined;
+  const configured = [
+    ...(driverCli.name === "claude-code" && Array.isArray(config.pluginDirs)
+      ? config.pluginDirs.map((path) => ({ kind: "plugin" as const, path }))
+      : []),
+    ...(Array.isArray(config.addDirs)
+      ? config.addDirs.map((path) => ({ kind: "read" as const, path }))
+      : []),
+    ...(driverCli.name === "claude-code" && isolation && Array.isArray(isolation.allowRead)
+      ? isolation.allowRead.map((path) => ({ kind: "read" as const, path }))
+      : []),
+  ].filter(
+    (entry): entry is { kind: "plugin" | "read"; path: string } =>
+      typeof entry.path === "string" && entry.path.length > 0,
+  );
+  return Promise.all(
+    configured
+      .sort((a, b) => `${a.kind}:${a.path}`.localeCompare(`${b.kind}:${b.path}`))
+      .map(async ({ kind, path }) => {
+        const absolute = resolve(baseRoot, path);
+        const key = `${kind}:${absolute}`;
+        let hash = cache.get(key);
+        if (!hash) {
+          hash = hashBehaviorDirectory(
+            absolute,
+            `driver/${kind}/${contentHash(absolute).slice(0, 12)}`,
+          ).then(valueHash);
+          cache.set(key, hash);
+        }
+        return {
+          kind,
+          path: absolute,
+          hash: await hash,
+        };
+      }),
+  );
+};

package/src/drivers/shared/experiment-policy.ts

@@ -0,0 +1,195 @@
+import { isAbsolute } from "node:path";
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  Boolean(value) && typeof value === "object" && !Array.isArray(value);
+
+const EXPERIMENT_BEHAVIOR_SOURCE_ARGS = new Set([
+  "--continue",
+  "-c",
+  "--fork-session",
+  "--resume",
+  "-r",
+  "--add-dir",
+  "--append-system-prompt-file",
+  "--mcp-config",
+  "--plugin-dir",
+  "--settings",
+  "--setting-sources",
+  "--system-prompt-file",
+]);
+
+const CODEX_EXPERIMENT_SOURCE_ARGS = new Set([
+  "--add-dir",
+  "--cd",
+  "-C",
+  "--config",
+  "-c",
+  "--profile",
+  "-p",
+]);
+
+const bindSubprocessExperimentConfig = (config: Record<string, unknown>): unknown => {
+  if (typeof config.command !== "string" || !isAbsolute(config.command)) {
+    throw new Error(
+      "experiment subprocess commands must be absolute direct wrappers so Lux can fingerprint the invoked behavior",
+    );
+  }
+  if (typeof config.cwd === "string") {
+    throw new Error(
+      "experiment runs do not allow an explicit subprocess cwd; use the candidate subject and staged fixtures",
+    );
+  }
+  if (Array.isArray(config.args) && config.args.length > 0) {
+    throw new Error(
+      "experiment subprocesses do not allow args; put stable behavior in the fingerprinted direct wrapper",
+    );
+  }
+  if (isRecord(config.env) && Object.keys(config.env).length > 0) {
+    throw new Error(
+      "experiment subprocesses do not allow custom env; put stable behavior in the fingerprinted direct wrapper",
+    );
+  }
+  return { ...config, inheritEnv: false };
+};
+
+type AgentDriverName = "claude-code" | "codex";
+
+const validateAgentExperimentConfig = (
+  driverName: AgentDriverName,
+  config: Record<string, unknown>,
+): { driverEnv: Record<string, unknown>; extraArgs: string[] } => {
+  const driverEnv = isRecord(config.env) ? config.env : {};
+  const commandResolutionOverride = Object.keys(driverEnv).find((name) =>
+    ["PATH", "PATHEXT"].includes(name.toUpperCase()),
+  );
+  if (commandResolutionOverride) {
+    throw new Error(
+      `experiment runs do not allow driver env.${commandResolutionOverride}; command resolution must match the fingerprinted host executable`,
+    );
+  }
+  if (typeof config.cwd === "string") {
+    throw new Error(
+      `experiment runs do not allow an explicit ${driverName} cwd; use the candidate subject and staged fixtures`,
+    );
+  }
+
+  const extraArgs = Array.isArray(config.extraArgs)
+    ? config.extraArgs.filter((value): value is string => typeof value === "string")
+    : [];
+  const disallowedArgs =
+    driverName === "claude-code" ? EXPERIMENT_BEHAVIOR_SOURCE_ARGS : CODEX_EXPERIMENT_SOURCE_ARGS;
+  const behaviorSourceArg = extraArgs.find((arg) =>
+    [...disallowedArgs].some((name) => arg === name || arg.startsWith(`${name}=`)),
+  );
+  if (behaviorSourceArg) {
+    throw new Error(
+      `experiment runs do not allow behavior-bearing extraArgs '${behaviorSourceArg}'; use structured driver fields so Lux can fingerprint the source`,
+    );
+  }
+
+  const isolation = isRecord(config.isolation) ? config.isolation : {};
+  const structuredPaths = [
+    ...(driverName === "claude-code" && Array.isArray(config.pluginDirs) ? config.pluginDirs : []),
+    ...(Array.isArray(config.addDirs) ? config.addDirs : []),
+    ...(driverName === "claude-code" && Array.isArray(isolation.allowRead)
+      ? isolation.allowRead
+      : []),
+  ].filter((value): value is string => typeof value === "string");
+  const relativeSource = structuredPaths.find((path) => !isAbsolute(path));
+  if (relativeSource) {
+    throw new Error(
+      `experiment driver source paths must be absolute after subjectPath binding: ${relativeSource}`,
+    );
+  }
+  return { driverEnv, extraArgs };
+};
+
+const bindCodexExperimentConfig = (
+  config: Record<string, unknown>,
+  extraArgs: readonly string[],
+): unknown => {
+  if (typeof config.profile === "string") {
+    throw new Error(
+      "experiment runs do not allow a Codex profile; use inline driver config so Lux can fingerprint it",
+    );
+  }
+  if (config.ephemeral === false) {
+    throw new Error("experiment runs require ephemeral Codex sessions");
+  }
+  const inlineConfig = isRecord(config.config) ? config.config : {};
+  const externalConfigKey = ((): string | undefined => {
+    const visit = (value: Record<string, unknown>, parent = ""): string | undefined => {
+      for (const [key, nested] of Object.entries(value)) {
+        const path = parent ? `${parent}.${key}` : key;
+        if (/(?:mcp_servers|instructions_file|notify|project_doc)/i.test(key)) return path;
+        if (isRecord(nested)) {
+          const found = visit(nested, path);
+          if (found) return found;
+        }
+      }
+      return undefined;
+    };
+    return visit(inlineConfig);
+  })();
+  if (externalConfigKey) {
+    throw new Error(
+      `experiment runs do not allow path-bearing Codex config '${externalConfigKey}'`,
+    );
+  }
+  const appServer = config.interactionMode !== "exec";
+  return {
+    ...config,
+    ephemeral: true,
+    ignoreUserConfig: true,
+    ignoreRules: !appServer,
+    ...(appServer && !config.isolation ? { isolation: { allowRead: [] } } : {}),
+    extraArgs,
+  };
+};
+
+const bindClaudeExperimentConfig = (
+  config: Record<string, unknown>,
+  extraArgs: readonly string[],
+  driverEnv: Record<string, unknown>,
+): unknown => {
+  if (config.isolation) return config;
+  return {
+    ...config,
+    extraArgs: [
+      ...extraArgs,
+      "--setting-sources",
+      "user",
+      "--strict-mcp-config",
+      "--settings",
+      JSON.stringify({ disableAllHooks: true }),
+    ],
+    env: {
+      ...driverEnv,
+      CLAUDE_CODE_DISABLE_AUTO_MEMORY: "1",
+      CLAUDE_CODE_DISABLE_CLAUDE_MDS: "1",
+      CLAUDE_CODE_SKIP_PROMPT_HISTORY: "1",
+      CLAUDE_CODE_DISABLE_BACKGROUND_TASKS: "1",
+      CLAUDE_CODE_AUTO_CONNECT_IDE: "false",
+      CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL: "1",
+      DISABLE_AUTOUPDATER: "1",
+    },
+  };
+};
+
+export const prepareClaudeExperimentConfig = <Cfg extends Record<string, unknown>>(
+  config: Cfg,
+): Cfg => {
+  const { driverEnv, extraArgs } = validateAgentExperimentConfig("claude-code", config);
+  return bindClaudeExperimentConfig(config, extraArgs, driverEnv) as Cfg;
+};
+
+export const prepareCodexExperimentConfig = <Cfg extends Record<string, unknown>>(
+  config: Cfg,
+): Cfg => {
+  const { extraArgs } = validateAgentExperimentConfig("codex", config);
+  return bindCodexExperimentConfig(config, extraArgs) as Cfg;
+};
+
+export const prepareSubprocessExperimentConfig = <Cfg extends Record<string, unknown>>(
+  config: Cfg,
+): Cfg => bindSubprocessExperimentConfig(config) as Cfg;