@prismatic-io/lux 0.0.1

package/src/orchestrator/experiment-runtime-identity.ts

@@ -0,0 +1,465 @@
+import { createHash } from "node:crypto";
+import { access, constants, lstat, open, readFile, realpath } from "node:fs/promises";
+import { homedir } from "node:os";
+import { delimiter, isAbsolute, join, resolve } from "node:path";
+import { z } from "zod";
+import { contentHash, discoverCliVersion, valueHash } from "../core/index.js";
+import { walkAuthoredFiles } from "./fs-read.js";
+import { boundExperimentDriverConfig } from "./orchestrator.js";
+
+export { LUX_VERSION } from "./package-version.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)),
+});
+
+export const referencedCli = (
+  reference: unknown,
+): { name: string; command: string } | undefined => {
+  let name: string | undefined;
+  if (typeof reference === "string") {
+    name = reference;
+  } else if (
+    typeof reference === "object" &&
+    reference !== null &&
+    typeof (reference as { name?: unknown }).name === "string"
+  ) {
+    name = (reference as { name: string }).name;
+  }
+  const config =
+    typeof reference === "object" && reference !== null
+      ? (reference as { config?: unknown }).config
+      : undefined;
+  if (name === "subprocess") {
+    if (
+      typeof config !== "object" ||
+      config === null ||
+      typeof (config as { command?: unknown }).command !== "string"
+    ) {
+      return undefined;
+    }
+    return { name, command: (config as { command: string }).command };
+  }
+  if (name !== "claude-code" && name !== "codex") return undefined;
+  let command = name === "codex" ? "codex" : "claude";
+  if (
+    typeof config === "object" &&
+    config !== null &&
+    typeof (config as { command?: unknown }).command === "string"
+  ) {
+    command = (config as { command: string }).command;
+  }
+  return { name, command };
+};
+
+export const referencedAnswererCli = (
+  reference: unknown,
+): { provider: "claude-code" | "codex"; command: string } | undefined => {
+  if (reference === "persona" || reference === "claude-code") {
+    return { provider: "claude-code", command: "claude" };
+  }
+  if (!reference || typeof reference !== "object") return undefined;
+  const name = (reference as { name?: unknown }).name;
+  const config = driverConfigRecord(reference);
+  if (name === "persona") {
+    const provider = config.provider === "codex" ? "codex" : "claude-code";
+    let command = provider === "codex" ? "codex" : "claude";
+    if (typeof config.command === "string") command = config.command;
+    return {
+      provider,
+      command,
+    };
+  }
+  if (name === "claude-code") {
+    return {
+      provider: "claude-code",
+      command: typeof config.command === "string" ? config.command : "claude",
+    };
+  }
+  return undefined;
+};
+
+const CliExecutableIdentitySchema = z
+  .object({
+    path: z.string(),
+    hash: z.string(),
+    mode: z.number().int().nonnegative(),
+    bytes: z.number().int().nonnegative(),
+  })
+  .strict();
+
+const CliIdentitySchema = z
+  .object({
+    command: z.string(),
+    version: z.string().nullable(),
+    executable: CliExecutableIdentitySchema.optional(),
+  })
+  .strict();
+type CliIdentity = z.infer<typeof CliIdentitySchema>;
+
+export const RuntimeCliReferenceSchema = z
+  .object({
+    command: z.string().min(1),
+    baseRoot: z.string().min(1),
+  })
+  .strict();
+export type RuntimeCliReference = z.infer<typeof RuntimeCliReferenceSchema>;
+
+const cliExecutableIdentityCache = new Map<
+  string,
+  Promise<z.infer<typeof CliExecutableIdentitySchema>>
+>();
+const cliVersionCache = new Map<string, Promise<string | null>>();
+
+const sameExecutableStat = (
+  left: Awaited<ReturnType<typeof lstat>>,
+  right: Awaited<ReturnType<typeof lstat>>,
+): boolean =>
+  left.dev === right.dev &&
+  left.ino === right.ino &&
+  left.mode === right.mode &&
+  left.size === right.size &&
+  left.mtimeMs === right.mtimeMs &&
+  left.ctimeMs === right.ctimeMs;
+
+const fingerprintCliExecutable = async (
+  path: string,
+  maximumBytes: number,
+): Promise<z.infer<typeof CliExecutableIdentitySchema>> => {
+  const initial = await lstat(path);
+  if (initial.isSymbolicLink() || !initial.isFile()) {
+    throw new Error(`experiment CLI command must be a regular file: ${path}`);
+  }
+  if (initial.size > maximumBytes) {
+    throw new Error(`experiment CLI command exceeds ${maximumBytes / 1024 / 1024} MiB: ${path}`);
+  }
+  const canonicalPath = await realpath(path);
+  const cacheKey = [
+    canonicalPath,
+    initial.dev,
+    initial.ino,
+    initial.mode,
+    initial.size,
+    initial.mtimeMs,
+    initial.ctimeMs,
+  ].join("\u0000");
+  const cached = cliExecutableIdentityCache.get(cacheKey);
+  if (cached) return cached;
+
+  const pending = (async () => {
+    const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+      const before = await handle.stat();
+      if (!sameExecutableStat(initial, before)) {
+        throw new Error(`experiment CLI command changed before fingerprinting: ${path}`);
+      }
+      const digest = createHash("sha256");
+      const buffer = Buffer.allocUnsafe(1024 * 1024);
+      let offset = 0;
+      while (offset < before.size) {
+        const length = Math.min(buffer.length, before.size - offset);
+        const { bytesRead } = await handle.read(buffer, 0, length, offset);
+        if (bytesRead === 0) {
+          throw new Error(`experiment CLI command changed while fingerprinting: ${path}`);
+        }
+        digest.update(buffer.subarray(0, bytesRead));
+        offset += bytesRead;
+      }
+      const after = await handle.stat();
+      const current = await lstat(path);
+      const currentCanonicalPath = await realpath(path);
+      if (
+        offset !== before.size ||
+        !sameExecutableStat(before, after) ||
+        !sameExecutableStat(after, current) ||
+        currentCanonicalPath !== canonicalPath
+      ) {
+        throw new Error(`experiment CLI command changed while fingerprinting: ${path}`);
+      }
+      return CliExecutableIdentitySchema.parse({
+        path: canonicalPath,
+        hash: digest.digest("hex"),
+        mode: after.mode,
+        bytes: after.size,
+      });
+    } finally {
+      await handle.close();
+    }
+  })();
+  cliExecutableIdentityCache.set(cacheKey, pending);
+  try {
+    return await pending;
+  } catch (error) {
+    if (cliExecutableIdentityCache.get(cacheKey) === pending) {
+      cliExecutableIdentityCache.delete(cacheKey);
+    }
+    throw error;
+  }
+};
+
+export const cliIdentity = async (command: string, baseRoot: string): Promise<CliIdentity> => {
+  const pathLike =
+    isAbsolute(command) ||
+    command.startsWith(".") ||
+    command.includes("/") ||
+    command.includes("\\");
+  if (pathLike && !isAbsolute(command)) {
+    throw new Error(
+      `custom experiment CLI command must be absolute for reproducible identity: ${resolve(baseRoot, command)}`,
+    );
+  }
+  let path: string;
+  if (pathLike) {
+    path = resolve(command);
+  } else {
+    const extensions =
+      process.platform === "win32"
+        ? (process.env.PATHEXT ?? ".EXE;.CMD;.BAT;.COM").split(";")
+        : [""];
+    let found: string | undefined;
+    for (const directory of (process.env.PATH ?? "").split(delimiter)) {
+      if (!directory || !isAbsolute(directory)) {
+        throw new Error(
+          `experiment PATH entries must be absolute and non-empty for reproducible command resolution: ${directory || "<empty>"}`,
+        );
+      }
+      for (const extension of extensions) {
+        const candidate = join(directory, `${command}${extension}`);
+        try {
+          await access(candidate, constants.X_OK);
+          found = await realpath(candidate);
+          break;
+        } catch {
+          // Try the next PATH entry.
+        }
+      }
+      if (found) break;
+    }
+    if (!found) throw new Error(`experiment CLI command was not found on PATH: ${command}`);
+    path = found;
+  }
+  // Current signed CLI bundles can exceed 256 MiB. Keep explicit paths
+  // tightly bounded while allowing installed single-file binaries.
+  const maximumBytes = pathLike ? 32 * 1024 * 1024 : 512 * 1024 * 1024;
+  const executable = await fingerprintCliExecutable(path, maximumBytes);
+  const versionKey = `${command}\u0000${executable.path}\u0000${executable.hash}`;
+  let version = cliVersionCache.get(versionKey);
+  if (!version) {
+    version = discoverCliVersion(executable.path).then((value) => value ?? null);
+    cliVersionCache.set(versionKey, version);
+  }
+  return CliIdentitySchema.parse({
+    command,
+    version: await version,
+    executable,
+  });
+};
+
+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 driverCli = referencedCli(driver);
+  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.
+  boundExperimentDriverConfig(driverCli.name, config, "identity-check");
+  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,
+        };
+      }),
+  );
+};
+
+export const runtimeCliIdentityHashForReferences = async (
+  references: readonly RuntimeCliReference[],
+): Promise<string> =>
+  valueHash(
+    await Promise.all(
+      references.map(async (reference) => ({
+        ...reference,
+        identity: await cliIdentity(reference.command, reference.baseRoot),
+      })),
+    ),
+  );