@skill-harness/core 0.30.0 → 0.31.0

package/dist/sources.js

@@ -1,9 +1,10 @@
 import { createHash } from "node:crypto";
-import { readFileSync, readdirSync } from "node:fs";
-import { isAbsolute, join, resolve } from "node:path";
+import { readFileSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
 import yaml from "js-yaml";
 import { resolveJudgeReferences } from "./judge-references.js";
 import { PROMPT_NORMALIZATION_SOURCE_DIGEST, PROMPT_NORMALIZATION_SOURCE_KEY } from "./prompt-normalization.js";
+import { fixtureInventory, hashFixtureFile } from "./util/fixture-inventory.js";
 export { PROMPT_NORMALIZATION_SOURCE_DIGEST, PROMPT_NORMALIZATION_SOURCE_KEY } from "./prompt-normalization.js";
 /**
  * What a run measured, as a map of `key -> sha256`, recorded in results.yaml so
@@ -114,42 +115,20 @@ export function fileSha256(path) {
  * normalised so a Linux-recorded hash still matches on Windows.
  */
 export function dirSha256(dir) {
-    let files;
     try {
-        files = walk(dir).sort();
-    }
-    catch {
-        return null;
-    }
-    const h = createHash("sha256");
-    for (const rel of files) {
-        h.update(rel);
-        h.update("\0");
-        try {
-            h.update(readFileSync(join(dir, rel)));
+        const files = fixtureInventory(dir);
+        const h = createHash("sha256");
+        for (const file of files) {
+            h.update(file.relative);
+            h.update("\0");
+            hashFixtureFile(h, file);
+            h.update("\0");
         }
-        catch {
-            return null; // a file that vanished mid-walk makes the whole digest untrustworthy
-        }
-        h.update("\0");
+        return h.digest("hex");
     }
-    return h.digest("hex");
-}
-/** Relative POSIX paths of every file under `dir`, recursively. Throws if `dir` is unreadable. */
-function walk(dir, prefix = "") {
-    const out = [];
-    for (const e of readdirSync(dir, { withFileTypes: true })) {
-        const rel = prefix ? `${prefix}/${e.name}` : e.name;
-        if (e.isDirectory()) {
-            out.push(...walk(join(dir, e.name), rel));
-        }
-        else if (e.isFile()) {
-            out.push(rel);
-        }
-        // symlinks/sockets/etc. are deliberately skipped: a fixture is plain files,
-        // and following links could hash something outside the fixture entirely.
+    catch {
+        return null; // Missing, oversized or changing input is unavailable evidence.
     }
-    return out;
 }
 /**
  * A scenario's semantic digest: everything that changes what the scenario

package/dist/util/exec.d.ts

@@ -1,12 +1,17 @@
+import { type ProcessObservation } from "./process.js";
 export interface ExecResult {
     stdout: string;
     stderr: string;
     code: number | null;
+    observation?: ProcessObservation;
 }
 export interface ExecOpts {
     cwd?: string;
     timeoutMs?: number;
     env?: NodeJS.ProcessEnv;
+    signal?: AbortSignal;
+    maxStdoutBytes?: number;
+    maxStderrBytes?: number;
 }
 /** Spawn a command, capture stdout/stderr. Never throws on non-zero exit; returns the code. */
 export declare function exec(cmd: string, args: string[], opts?: ExecOpts): Promise<ExecResult>;

package/dist/util/exec.js

@@ -1,38 +1,22 @@
-import { spawn } from "node:child_process";
 import { existsSync } from "node:fs";
 import { join, delimiter } from "node:path";
+import { BoundedCapture, ProcessOutputLimitError, runProcess } from "./process.js";
 /** Spawn a command, capture stdout/stderr. Never throws on non-zero exit; returns the code. */
-export function exec(cmd, args, opts = {}) {
-    return new Promise((resolve, reject) => {
-        // stdin must be ignored (not inherited): pi blocks reading stdin even in
-        // --print mode if its stdin is an open pipe/tty.
-        const child = spawn(cmd, args, {
-            cwd: opts.cwd,
-            env: opts.env ?? process.env,
-            stdio: ["ignore", "pipe", "pipe"],
-        });
-        let stdout = "";
-        let stderr = "";
-        let timer;
-        if (opts.timeoutMs) {
-            timer = setTimeout(() => {
-                child.kill("SIGKILL");
-                stderr += `\n[skill-harness] killed after ${opts.timeoutMs}ms timeout`;
-            }, opts.timeoutMs);
-        }
-        child.stdout.on("data", (d) => (stdout += d.toString()));
-        child.stderr.on("data", (d) => (stderr += d.toString()));
-        child.on("error", (e) => {
-            if (timer)
-                clearTimeout(timer);
-            reject(e);
-        });
-        child.on("close", (code) => {
-            if (timer)
-                clearTimeout(timer);
-            resolve({ stdout, stderr, code });
-        });
-    });
+export async function exec(cmd, args, opts = {}) {
+    const stdout = new BoundedCapture(opts.maxStdoutBytes ?? 8 * 1024 * 1024);
+    const stderr = new BoundedCapture(opts.maxStderrBytes ?? 128 * 1024);
+    const capture = (sink, name) => (chunk) => {
+        sink.push(chunk);
+        if (sink.truncated)
+            throw new ProcessOutputLimitError(`${name} capture exceeded ${sink.limit} bytes`);
+    };
+    const result = await runProcess(cmd, args, { ...opts,
+        onStdout: capture(stdout, "stdout"), onStderr: capture(stderr, "stderr") });
+    // A partial command output must never masquerade as a successful judge answer,
+    // git diff, or tool lookup. Ordinary non-zero exits remain the caller's decision.
+    if (result.error)
+        throw result.error;
+    return { stdout: stdout.text(), stderr: stderr.text(), code: result.code, observation: result.observation };
 }
 /** True if a binary is resolvable on PATH. */
 export function onPath(bin) {

package/dist/util/fixture-inventory.d.ts

@@ -0,0 +1,19 @@
+import type { Hash } from "node:crypto";
+export declare const FIXTURE_LIMITS: Readonly<{
+    entries: 4096;
+    depth: 32;
+    fileBytes: number;
+    totalBytes: number;
+}>;
+export declare class FixtureLimitError extends Error {
+    constructor(message: string);
+}
+export interface FixtureFile {
+    path: string;
+    relative: string;
+    size: number;
+}
+/** Bounded metadata walk of one explicitly selected tree. Never follows child symlinks. */
+export declare function fixtureInventory(root: string, skip?: (name: string, relative: string) => boolean): FixtureFile[];
+/** Update the existing hash format without allocating a whole file or accepting a growing file. */
+export declare function hashFixtureFile(hash: Hash, file: FixtureFile): void;

package/dist/util/fixture-inventory.js

@@ -0,0 +1,68 @@
+import { closeSync, constants, fstatSync, lstatSync, openSync, opendirSync, readSync } from "node:fs";
+import { join } from "node:path";
+export const FIXTURE_LIMITS = Object.freeze({ entries: 4096, depth: 32, fileBytes: 64 * 1024 * 1024, totalBytes: 256 * 1024 * 1024 });
+export class FixtureLimitError extends Error {
+    constructor(message) { super(`Selected fixture limit exceeded: ${message}`); this.name = "FixtureLimitError"; }
+}
+/** Bounded metadata walk of one explicitly selected tree. Never follows child symlinks. */
+export function fixtureInventory(root, skip) {
+    const files = [];
+    let entries = 0, total = 0;
+    const walk = (dir, prefix, depth) => {
+        if (depth > FIXTURE_LIMITS.depth)
+            throw new FixtureLimitError(`depth exceeds ${FIXTURE_LIMITS.depth}`);
+        const opened = opendirSync(dir);
+        try {
+            for (let entry = opened.readSync(); entry; entry = opened.readSync()) {
+                if (++entries > FIXTURE_LIMITS.entries)
+                    throw new FixtureLimitError(`more than ${FIXTURE_LIMITS.entries} entries`);
+                const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
+                if (skip?.(entry.name, relative))
+                    continue;
+                const path = join(dir, entry.name);
+                if (entry.isDirectory())
+                    walk(path, relative, depth + 1);
+                else if (entry.isFile()) {
+                    const stat = lstatSync(path);
+                    if (!stat.isFile())
+                        throw new Error(`Selected fixture changed during inventory: ${relative}`);
+                    if (stat.size > FIXTURE_LIMITS.fileBytes)
+                        throw new FixtureLimitError(`${relative} exceeds ${FIXTURE_LIMITS.fileBytes} bytes`);
+                    total += stat.size;
+                    if (total > FIXTURE_LIMITS.totalBytes)
+                        throw new FixtureLimitError(`total exceeds ${FIXTURE_LIMITS.totalBytes} bytes`);
+                    files.push({ path, relative, size: stat.size });
+                }
+            }
+        }
+        finally {
+            opened.closeSync();
+        }
+    };
+    walk(root, "", 0);
+    return files.sort((a, b) => a.relative < b.relative ? -1 : a.relative > b.relative ? 1 : 0);
+}
+/** Update the existing hash format without allocating a whole file or accepting a growing file. */
+export function hashFixtureFile(hash, file) {
+    const fd = openSync(file.path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    try {
+        const stat = fstatSync(fd);
+        if (!stat.isFile() || stat.size !== file.size || stat.size > FIXTURE_LIMITS.fileBytes)
+            throw new Error(`Selected fixture changed before hashing: ${file.relative}`);
+        const buffer = Buffer.allocUnsafe(64 * 1024);
+        let offset = 0;
+        while (offset < file.size) {
+            const count = readSync(fd, buffer, 0, Math.min(buffer.length, file.size - offset), offset);
+            if (!count)
+                throw new Error(`Selected fixture changed while hashing: ${file.relative}`);
+            hash.update(buffer.subarray(0, count));
+            offset += count;
+        }
+        if (readSync(fd, buffer, 0, 1, offset) !== 0 || fstatSync(fd).size !== file.size)
+            throw new Error(`Selected fixture changed while hashing: ${file.relative}`);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+//# sourceMappingURL=fixture-inventory.js.map

package/dist/util/process.d.ts

@@ -0,0 +1,78 @@
+export interface ProcessObservation {
+    schema: 1;
+    platform: string;
+    scope: "owned-process-group" | "child-process";
+    pid: number | null;
+    reason: "running" | "exited" | "timeout" | "aborted" | "output-limit" | "resource-limit" | "spawn-error";
+    code: number | null;
+    durationMs: number;
+    stdoutBytes: number;
+    stderrBytes: number;
+    samples: number;
+    processesObserved: number;
+    peakRssBytes: number | null;
+    cpuUserTicks: number | null;
+    cpuSystemTicks: number | null;
+    readBytes: number | null;
+    writeBytes: number | null;
+    gaps: string[];
+    cleanup: {
+        termSent: boolean;
+        killSent: boolean;
+        groupGone: boolean | null;
+        pipesClosed: boolean;
+    };
+}
+export interface ProcessScope {
+    signal?: AbortSignal;
+    /** One metadata-only record on settlement; never receives argv, environment or output. */
+    onObservation?: (record: ProcessObservation) => void;
+    /** Latest active metadata, initially and at most every five seconds; never raw logs. */
+    onSample?: (record: ProcessObservation) => void;
+    /** Optional owned-tree sampled limits; these are not host quotas or sandbox boundaries. */
+    maxRssBytes?: number;
+    maxWriteBytes?: number;
+}
+/** Scope all subprocesses in an evaluation, including concurrent subject/judge calls. */
+export declare function withProcessScope<T>(scope: ProcessScope, work: () => T): T;
+export declare class ProcessControlError extends Error {
+    readonly reason: "aborted" | "output-limit" | "resource-limit";
+    constructor(reason: "aborted" | "output-limit" | "resource-limit", message: string);
+}
+export declare class ProcessOutputLimitError extends ProcessControlError {
+    constructor(message: string);
+}
+export declare function isProcessControlError(error: unknown): error is ProcessControlError;
+export declare function getProcessSignal(): AbortSignal | undefined;
+export declare function throwIfProcessAborted(): void;
+/** Retains at most `limit` bytes, including a single oversized chunk. */
+export declare class BoundedCapture {
+    readonly limit: number;
+    private chunks;
+    private tailUsed;
+    bytes: number;
+    truncated: boolean;
+    constructor(limit: number);
+    push(chunk: Buffer): void;
+    text(): string;
+}
+export interface ProcessOptions {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    /** Total stream traffic ceiling, independent of how much a consumer retains. */
+    maxOutputBytes?: number;
+    onStdout?: (chunk: Buffer) => void;
+    onStderr?: (chunk: Buffer) => void;
+    onStdoutEnd?: () => void;
+    /** Internal/test seam; not a model execution budget. */
+    killGraceMs?: number;
+}
+export interface ProcessResult {
+    code: number | null;
+    observation: ProcessObservation;
+    error: Error | null;
+}
+/** Shared owned-process lifecycle. Callers retain only their bounded stream representation. */
+export declare function runProcess(command: string, args: string[], options?: ProcessOptions): Promise<ProcessResult>;