@prismatic-io/lux 0.0.2-preview.33 → 0.0.2-preview.36

package/lib/drivers/shared/skills.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills.js","sourceRoot":"","sources":["../../../src/drivers/shared/skills.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prismatic-io/lux",
-  "version": "0.0.2-preview.33",
+  "version": "0.0.2-preview.36",
   "description": "Coding-agent evaluation and improvement with deterministic assertions, optional LLM judges, and first-class human-in-the-loop runs.",
   "license": "MIT",
   "homepage": "https://github.com/prismatic-io/lux",
@@ -79,6 +79,7 @@
     "tinyexec": "1.2.4",
     "tinyglobby": "^0.2.17",
     "xstate": "5.32.0",
+    "yaml": "^2.9.0",
     "zod": "^4.4.3"
   }
 }

package/skills/lux-answerer/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: lux-answerer
-version: 0.0.2-preview.33
+version: 0.0.2-preview.36
 description: Play the persona for a running Lux orchestrator that uses the claude-code answerer. Read structured events on stdout, decide answers from persona + context, write JSON to its answer channel.
 user-invocable: false
 allowed-tools: Bash, Read

package/src/assertions/rubric/index.ts

@@ -130,7 +130,16 @@ Rules:
 ${
   scoring === "binary"
     ? "- score must be exactly 1 (pass) or 0 (fail), never a fractional number. Pass only when the evidence establishes every required behavior in this criterion. A demonstrated violation of any required behavior fails; other successes cannot compensate. Cite the decisive evidence. Abstain if missing evidence prevents deciding, rather than awarding partial credit."
-    : "- score is a continuous number in [0, 1]."
+    : `- score is a continuous number in [0, 1], proportional to the demonstrated
+  requested outcomes within this criterion, weighted by their importance to the
+  task. Grade this criterion, not the whole task or unrelated criteria.
+- Credit independently working parts even when another part is missing or
+  incorrect. Use intermediate values throughout the range; do not round to a
+  verdict, impose score bands, or adjust a score to cross an acceptance threshold.
+- Zero means no demonstrated credit; one means the requested outcome is fully
+  demonstrated. Optional polish is outside the denominator. Do not invent gaps
+  to avoid awarding full credit, require perfection beyond the request, or force
+  scores into a distribution.`
 }
 - Missing or truncated evidence is not proof of failure or success. Abstain when
   it prevents a supported judgment; do not guess a score.

package/src/assertions/rubric/internal.ts

@@ -3,7 +3,7 @@ import {
   matchesAnyGlob,
   type Run,
   type RunEvent,
-  readRunArtifactText,
+  readRunArtifactExcerpt,
   tryParseJson,
 } from "../../core/index.js";
 import type { RubricConfig, RubricEvidence } from "./index.js";
@@ -371,21 +371,35 @@ export const sampleArtifacts = async (
   const listed = artifactListing(selected.map((artifact) => artifact.path));
   const out: string[] = [
     `Files selected (${selected.length} of ${run.artifacts.length}):\n${listed.join("\n")}`,
+    "Selection counts refer to captured paths matching this criterion, not capture failures. Listed files are not necessarily shown in full below.",
   ];
-  if (evidence?.includeArtifactContents === false) return out.join("\n\n");
+  if (evidence?.includeArtifactContents === false) {
+    out.push("[File contents excluded by the evidence selector.]");
+    return out.join("\n\n");
+  }
   let budget = Math.min(evidence?.maxArtifactChars ?? 60_000, MAX_ARTIFACT_CHARS);
-  for (const artifact of selected) {
-    if (budget <= 0) break;
+  // Empty and unreadable files still cost framing; do not let them evade the cap.
+  let framingBudget = 8_000;
+  for (const [index, artifact] of selected.entries()) {
+    const path = boundedText(artifact.path, 500, "artifact path");
+    if (budget <= 0 || framingBudget < path.length + 100) {
+      out.push(
+        `[Content omitted for ${selected.length - index} remaining selected file(s): artifact ${budget <= 0 ? "character" : "framing"} budget exhausted.]`,
+      );
+      break;
+    }
     const limit = Math.min(perFileLimit, budget);
-    const content = await readRunArtifactText(run, artifact.path, {
-      // Four UTF-8 bytes per requested character preserves the character cap.
-      maxBytes: Math.max(1, limit * 4),
-    })
-      .then((text) => text.slice(0, limit))
-      .catch(() => null);
-    if (content === null) continue;
-    budget -= content.length;
-    out.push(`--- ${artifact.path} ---\n${content}`);
+    const content = await readRunArtifactExcerpt(run, artifact.path, limit).catch(() => null);
+    if (content === null) {
+      const marker = `[Content unavailable: ${path}. The captured file could not be read safely.]`;
+      framingBudget -= marker.length + 2;
+      out.push(marker);
+      continue;
+    }
+    budget -= content.text.length;
+    const block = `--- ${path} ---\n${content.text}${content.truncated ? "\n[File excerpt truncated; omitted content is unassessed.]" : ""}`;
+    framingBudget -= block.length - content.text.length + 2;
+    out.push(block);
   }
   return out.join("\n\n");
 };

package/src/core/artifact-evidence.ts

@@ -188,6 +188,7 @@ export const readInspectedFileBytes = async (
   expected: Stats,
   maxBytes: number,
   label: string,
+  prefixOnly = false,
 ): Promise<Buffer> => {
   if (!Number.isSafeInteger(maxBytes) || maxBytes < 0 || maxBytes > MAX_ARTIFACT_READ_BYTES) {
     throw new RangeError(
@@ -195,7 +196,7 @@ export const readInspectedFileBytes = async (
     );
   }
   if (!expected.isFile()) throw new Error(`${label} is not a file`);
-  if (expected.size > maxBytes) {
+  if (!prefixOnly && expected.size > maxBytes) {
     throw new Error(`${label} exceeds the ${maxBytes}-byte artifact read limit`);
   }
 
@@ -210,23 +211,24 @@ export const readInspectedFileBytes = async (
       if (opened.size !== expected.size) {
         throw new Error(`${label} changed while it was being inspected`);
       }
-      if (opened.size > maxBytes) {
+      if (!prefixOnly && opened.size > maxBytes) {
         throw new Error(`${label} exceeds the ${maxBytes}-byte artifact read limit`);
       }
       // Allocate for the inspected file, not the caller's ceiling. Reading one
       // extra byte detects same-inode growth after fstat without making many
       // tiny artifact reads reserve the maximum concurrently.
-      const bytes = Buffer.alloc(expected.size + 1);
+      const size = Math.min(expected.size, maxBytes);
+      const bytes = Buffer.alloc(size + 1);
       let offset = 0;
       while (offset < bytes.length) {
         const read = await handle.read(bytes, offset, bytes.length - offset, offset);
         if (read.bytesRead === 0) break;
         offset += read.bytesRead;
       }
-      if (offset !== expected.size) {
+      if (offset !== Math.min(expected.size, bytes.length)) {
         throw new Error(`${label} changed while it was being inspected`);
       }
-      return bytes.subarray(0, offset);
+      return bytes.subarray(0, Math.min(offset, size));
     } finally {
       await handle.close();
     }
@@ -238,6 +240,39 @@ export const readInspectedFileBytes = async (
   }
 };
 
+/** Read a bounded prefix for presentation without weakening full-evidence reads. */
+export const readRunArtifactExcerpt = async (
+  run: RunArtifactEvidence,
+  authoredPath: string,
+  maxChars: number,
+): Promise<{ text: string; truncated: boolean }> => {
+  if (!Number.isSafeInteger(maxChars) || maxChars < 0 || maxChars > 80_000) {
+    throw new RangeError("artifact excerpt maxChars must be an integer from 0 to 80000");
+  }
+  const inspected = await inspectRunArtifact(run, authoredPath);
+  if (!inspected.stats?.isFile()) {
+    throw new Error(inspected.issue ?? `${authoredPath} is not a file`);
+  }
+  // An extra character distinguishes an exact fit from an omitted suffix.
+  const bytes = await readInspectedFileBytes(
+    inspected.target,
+    inspected.stats,
+    (maxChars + 1) * 4,
+    authoredPath,
+    true,
+  );
+  const text = bytes.toString("utf8");
+  let end = Math.min(maxChars, text.length);
+  if (
+    end > 0 &&
+    end < text.length &&
+    /[\uD800-\uDBFF]/.test(text[end - 1] ?? "") &&
+    /[\uDC00-\uDFFF]/.test(text[end] ?? "")
+  )
+    end--;
+  return { text: text.slice(0, end), truncated: text.length > end };
+};
+
 export const readRunArtifactBytes = async (
   run: RunArtifactEvidence,
   authoredPath: string,

package/src/core/model-cli.ts

@@ -1,4 +1,5 @@
-import { rm } from "node:fs/promises";
+import { rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
 import { temporaryDirectory } from "tempy";
 import { z } from "zod";
 import {
@@ -155,6 +156,10 @@ const runClaude = async (
   const model = options.model ?? DEFAULT_CLAUDE_MODEL;
   const workspace = temporaryDirectory({ prefix: "lux-claude-model-" });
   try {
+    // Windows command shims cannot preserve multiline argv. Keep the exact
+    // system instructions in the private workspace for the call's lifetime.
+    const systemPromptPath = join(workspace, "system-prompt.txt");
+    await writeFile(systemPromptPath, options.system, { mode: 0o600 });
     const effort = resolveEffort("claude-code", model, options.reasoningEffort);
     const result = await exec(
       command,
@@ -183,8 +188,8 @@ const runClaude = async (
           : []),
         "--settings",
         JSON.stringify({ disableAllHooks: true }),
-        "--system-prompt",
-        options.system,
+        "--system-prompt-file",
+        systemPromptPath,
       ],
       {
         input: options.prompt,

package/src/drivers/claude-code/index.ts

@@ -28,6 +28,7 @@ import {
   configuredClaudeSourceHashes,
 } from "../shared/experiment-behavior.js";
 import { prepareClaudeExperimentConfig } from "../shared/experiment-policy.js";
+import { stageSkills } from "../shared/skills.js";
 import { subprocessDriver } from "../subprocess/index.js";
 import { runDeferredProcess } from "./deferred-process.js";
 import { isolatedLaunch } from "./isolation.js";
@@ -106,6 +107,8 @@ export const ClaudeCodeDriverConfigSchema = z
     agent: z.string().optional(),
     /** Extra readable directories (`--add-dir`). Grant the narrowest tree the case needs. */
     addDirs: z.array(z.string()).optional(),
+    /** Standalone skill directories registered through native discovery in an isolated workspace. */
+    skillDirs: z.array(z.string().min(1)).optional(),
     /**
      * Run in a disposable workspace with local memory, persisted runs, and
      * standard credential stores denied. Live network access is retained.
@@ -132,6 +135,13 @@ export const ClaudeCodeDriverConfigSchema = z
   })
   .strict()
   .superRefine((config, ctx) => {
+    if (config.skillDirs?.length && !config.isolation) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["skillDirs"],
+        message: "skillDirs requires isolation",
+      });
+    }
     if (config.turnTimeout !== undefined && config.interactionMode !== "defer-resume") {
       ctx.addIssue({
         code: "custom",
@@ -173,7 +183,7 @@ export const ClaudeCodeDriverConfigSchema = z
         code: "custom",
         path: ["pluginDirs"],
         message:
-          "isolated defer-resume cannot load plugin hooks; use addDirs for read-only skill files",
+          "isolated defer-resume cannot load plugin hooks; use skillDirs for standalone skills",
       });
     }
     if (config.cwd || config.cwdMode !== "artifacts") {
@@ -571,6 +581,7 @@ class ClaudeCodeDriverImpl implements AgentDriver {
       temporaryDirectory({ prefix: "lux-claude-control-" }),
     );
     await cp(ctx.artifactsDir, this.isolatedWorkspace, { recursive: true });
+    await stageSkills(this.config.skillDirs ?? [], this.isolatedWorkspace, ".claude");
     return isolatedLaunch(this.config, ctx, this.isolatedWorkspace, this.isolationControlDir);
   }
 

package/src/drivers/codex/config.ts

@@ -39,6 +39,8 @@ export const CodexDriverConfigSchema = z
     env: z.record(z.string(), z.string()).optional(),
     inheritEnv: InheritEnvironmentSchema.optional(),
     addDirs: z.array(z.string()).optional(),
+    /** Standalone skill directories registered through native discovery in an isolated workspace. */
+    skillDirs: z.array(z.string().min(1)).optional(),
     profile: z.string().optional(),
     config: z.record(z.string(), CodexConfigValueSchema).optional(),
     extraArgs: z.array(z.string()).optional(),
@@ -58,6 +60,13 @@ export const CodexDriverConfigSchema = z
   })
   .strict()
   .superRefine((config, ctx) => {
+    if (config.skillDirs?.length && !config.isolation) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["skillDirs"],
+        message: "skillDirs requires isolation",
+      });
+    }
     if (
       config.approvalsReviewer === "auto_review" &&
       (config.interactionMode !== "app-server" || config.approvalPolicy !== "on-request")

package/src/drivers/codex/index.ts

@@ -24,6 +24,7 @@ import { copyRegularFileNoFollow } from "../../core/secure-copy.js";
 import { walkArtifacts } from "../shared/artifacts.js";
 import { configuredClaudeSourceHashes } from "../shared/experiment-behavior.js";
 import { prepareCodexExperimentConfig } from "../shared/experiment-policy.js";
+import { stageSkills } from "../shared/skills.js";
 import { subprocessDriver } from "../subprocess/index.js";
 import {
   type AppTurnFacets,
@@ -104,6 +105,7 @@ class CodexAppServerDriverImpl implements AgentDriver {
       const workspace = await realpath(temporaryDirectory({ prefix: "lux-codex-workspace-" }));
       await cp(ctx.artifactsDir, workspace, { recursive: true });
       this.isolatedWorkspace = workspace;
+      await stageSkills(this.config.skillDirs ?? [], workspace, ".agents");
       cwd = workspace;
     }
     if (this.config.isolation || this.config.ignoreUserConfig) {

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

@@ -162,7 +162,7 @@ export const configuredClaudeSourceHashes = async (
   driver: unknown,
   baseRoot: string,
   cache: Map<string, Promise<string>> = new Map(),
-): Promise<Array<{ kind: "plugin" | "read"; path: string; hash: string }>> => {
+): Promise<Array<{ kind: "plugin" | "read" | "skill"; 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;
@@ -183,11 +183,14 @@ export const configuredClaudeSourceHashes = async (
     ...(Array.isArray(config.addDirs)
       ? config.addDirs.map((path) => ({ kind: "read" as const, path }))
       : []),
+    ...(Array.isArray(config.skillDirs)
+      ? config.skillDirs.map((path) => ({ kind: "skill" 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 } =>
+    (entry): entry is { kind: "plugin" | "read" | "skill"; path: string } =>
       typeof entry.path === "string" && entry.path.length > 0,
   );
   return Promise.all(

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

@@ -91,6 +91,7 @@ const validateAgentExperimentConfig = (
   const structuredPaths = [
     ...(driverName === "claude-code" && Array.isArray(config.pluginDirs) ? config.pluginDirs : []),
     ...(Array.isArray(config.addDirs) ? config.addDirs : []),
+    ...(Array.isArray(config.skillDirs) ? config.skillDirs : []),
     ...(driverName === "claude-code" && Array.isArray(isolation.allowRead)
       ? isolation.allowRead
       : []),

package/src/drivers/shared/skills.ts

@@ -0,0 +1,74 @@
+import { lstat, mkdir, readFile, realpath } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+import { parse } from "yaml";
+import { walkAuthoredFiles } from "../../core/file-tree.js";
+import { copyRegularFileNoFollow } from "../../core/secure-copy.js";
+
+const validateSkillMetadata = async (root: string, file: string, name: string): Promise<void> => {
+  const text = await readFile(join(root, file), "utf8");
+  const frontmatter = /^\uFEFF?---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(text);
+  if (!frontmatter) throw new Error(`skill requires YAML frontmatter: ${file}`);
+  const metadata: unknown = parse(frontmatter[1] ?? "", { maxAliasCount: 50, merge: true });
+  if (!metadata || typeof metadata !== "object" || Array.isArray(metadata))
+    throw new Error(`skill frontmatter must be a mapping: ${file}`);
+  if ("hooks" in metadata) throw new Error(`isolated skills cannot define hooks: ${file}`);
+  if (file === "SKILL.md" && (!("name" in metadata) || metadata.name !== name))
+    throw new Error(`skill frontmatter name must match its directory: ${name}`);
+};
+
+/** Install only explicitly supplied, standalone skills into native project discovery. */
+export const stageSkills = async (
+  directories: readonly string[],
+  workspace: string,
+  host: ".claude" | ".agents",
+): Promise<void> => {
+  const names = new Set<string>();
+  for (const directory of directories) {
+    const requestedRoot = resolve(directory);
+    const metadata = await lstat(requestedRoot);
+    if (metadata.isSymbolicLink() || !metadata.isDirectory())
+      throw new Error(`skill source must be a real directory: ${requestedRoot}`);
+    const root = await realpath(requestedRoot);
+    const name = basename(root);
+    if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name))
+      throw new Error(`skill directory must use a portable skill name: ${name}`);
+    if (names.has(name)) throw new Error(`duplicate skill directory name: ${name}`);
+    names.add(name);
+    const files = await walkAuthoredFiles(root);
+    if (!files.includes("SKILL.md")) throw new Error(`skill source lacks SKILL.md: ${root}`);
+    if (files.length > 5_000) throw new Error(`skill source exceeds 5000 files: ${root}`);
+    let bytes = 0;
+    for (const file of files) {
+      const parts = file.split(/[\\/]/);
+      if (
+        parts.some((part) =>
+          [".claude-plugin", ".claude", ".codex", ".agents", ".git", ".jj"].includes(part),
+        ) ||
+        parts.some((part) => [".mcp.json", ".lsp.json"].includes(part)) ||
+        parts.join("/").endsWith("hooks/hooks.json")
+      )
+        throw new Error(`skill source contains plugin or agent configuration: ${file}`);
+      bytes += (await lstat(join(root, file))).size;
+      if (bytes > 256 * 1024 * 1024) throw new Error(`skill source exceeds 256 MiB: ${root}`);
+      if (basename(file) === "SKILL.md") await validateSkillMetadata(root, file, name);
+    }
+    // Never follow a fixture-owned discovery directory or replace an authored skill.
+    let parent = workspace;
+    for (const part of [host, "skills"]) {
+      parent = join(parent, part);
+      await mkdir(parent).catch((error: NodeJS.ErrnoException) => {
+        if (error.code !== "EEXIST") throw error;
+      });
+      const info = await lstat(parent);
+      if (info.isSymbolicLink() || !info.isDirectory())
+        throw new Error(`skill discovery path must be a real directory: ${parent}`);
+    }
+    const destination = join(parent, name);
+    await mkdir(destination);
+    for (const file of files) {
+      const target = join(destination, file);
+      await mkdir(dirname(target), { recursive: true });
+      await copyRegularFileNoFollow(root, join(root, file), target);
+    }
+  }
+};