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

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/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);
+    }
+  }
+};