cclaw-cli 0.49.0 → 0.51.1

package/dist/eval/runs.d.ts

@@ -1,41 +0,0 @@
-export declare const RUNS_DIR = "runs";
-export interface EvalRunStatus {
-    id: string;
-    startedAt: string;
-    endedAt?: string;
-    pid: number;
-    argv: string[];
-    cwd: string;
-    exitCode?: number;
-    state: "running" | "succeeded" | "failed";
-}
-export declare function runsRoot(projectRoot: string): string;
-export declare function runDir(projectRoot: string, id: string): string;
-export declare function runLogPath(projectRoot: string, id: string): string;
-export declare function runStatusPath(projectRoot: string, id: string): string;
-/**
- * Generate a short, lexicographically-sortable run id. The timestamp
- * prefix means `ls -1` already returns the runs in chronological order
- * which keeps the `runs list` subcommand trivial.
- */
-export declare function generateRunId(now?: Date): string;
-export declare function ensureRunDir(projectRoot: string, id: string): Promise<string>;
-export declare function writeRunStatus(projectRoot: string, status: EvalRunStatus): Promise<void>;
-export declare function readRunStatus(projectRoot: string, id: string): Promise<EvalRunStatus | null>;
-/**
- * List run ids under `.cclaw/evals/runs/`, most recent first. Directory
- * entries that don't contain a `run.json` are skipped (half-initialized
- * or manually mkdir'd folders).
- */
-export declare function listRuns(projectRoot: string): Promise<EvalRunStatus[]>;
-/**
- * Resolve `"latest"` (or undefined) to the most recent run id.
- * Returns `null` when there are no runs.
- */
-export declare function resolveRunId(projectRoot: string, hint: string | undefined): Promise<string | null>;
-/**
- * Cheap liveness probe for an EvalRunStatus. A `run.json` can be stale
- * (process crashed mid-commit), so we double-check with `kill(pid, 0)`
- * before trusting the `state: "running"` field.
- */
-export declare function isRunAlive(status: EvalRunStatus): boolean;

package/dist/eval/runs.js

@@ -1,114 +0,0 @@
-/**
- * Run bookkeeping for backgrounded `cclaw eval` invocations.
- *
- * A backgrounded run writes three artifacts under `.cclaw/evals/runs/<id>/`:
- *
- *   - `run.json`  — status metadata (pid, started/ended ISO timestamps,
- *                    exit code, argv, cwd). Updated at start and at exit.
- *   - `run.log`   — combined stdout+stderr of the child process. This is
- *                    what `cclaw eval runs tail` streams.
- *   - `run.pid`   — just the pid, written atomically so `runs status`
- *                    can probe liveness without parsing JSON.
- *
- * The `id` is a short alphanumeric string (8 chars + ISO timestamp prefix)
- * chosen so sorting directory entries by name produces a chronological
- * listing without any extra work.
- */
-import { randomBytes } from "node:crypto";
-import fs from "node:fs/promises";
-import path from "node:path";
-import { EVALS_ROOT } from "../constants.js";
-import { exists } from "../fs-utils.js";
-export const RUNS_DIR = "runs";
-export function runsRoot(projectRoot) {
-    return path.join(projectRoot, EVALS_ROOT, RUNS_DIR);
-}
-export function runDir(projectRoot, id) {
-    return path.join(runsRoot(projectRoot), id);
-}
-export function runLogPath(projectRoot, id) {
-    return path.join(runDir(projectRoot, id), "run.log");
-}
-export function runStatusPath(projectRoot, id) {
-    return path.join(runDir(projectRoot, id), "run.json");
-}
-/**
- * Generate a short, lexicographically-sortable run id. The timestamp
- * prefix means `ls -1` already returns the runs in chronological order
- * which keeps the `runs list` subcommand trivial.
- */
-export function generateRunId(now = new Date()) {
-    const ts = now.toISOString().replace(/[-:]/g, "").replace(/\.\d+Z$/, "Z");
-    const suffix = randomBytes(3).toString("hex");
-    return `${ts}-${suffix}`;
-}
-export async function ensureRunDir(projectRoot, id) {
-    const dir = runDir(projectRoot, id);
-    await fs.mkdir(dir, { recursive: true });
-    return dir;
-}
-export async function writeRunStatus(projectRoot, status) {
-    await ensureRunDir(projectRoot, status.id);
-    await fs.writeFile(runStatusPath(projectRoot, status.id), `${JSON.stringify(status, null, 2)}\n`, "utf8");
-}
-export async function readRunStatus(projectRoot, id) {
-    const file = runStatusPath(projectRoot, id);
-    if (!(await exists(file)))
-        return null;
-    try {
-        const raw = await fs.readFile(file, "utf8");
-        return JSON.parse(raw);
-    }
-    catch {
-        return null;
-    }
-}
-/**
- * List run ids under `.cclaw/evals/runs/`, most recent first. Directory
- * entries that don't contain a `run.json` are skipped (half-initialized
- * or manually mkdir'd folders).
- */
-export async function listRuns(projectRoot) {
-    const root = runsRoot(projectRoot);
-    if (!(await exists(root)))
-        return [];
-    const entries = await fs.readdir(root, { withFileTypes: true });
-    const out = [];
-    for (const entry of entries) {
-        if (!entry.isDirectory())
-            continue;
-        const status = await readRunStatus(projectRoot, entry.name);
-        if (status)
-            out.push(status);
-    }
-    out.sort((a, b) => (a.startedAt < b.startedAt ? 1 : -1));
-    return out;
-}
-/**
- * Resolve `"latest"` (or undefined) to the most recent run id.
- * Returns `null` when there are no runs.
- */
-export async function resolveRunId(projectRoot, hint) {
-    if (hint && hint !== "latest") {
-        const status = await readRunStatus(projectRoot, hint);
-        return status ? hint : null;
-    }
-    const runs = await listRuns(projectRoot);
-    return runs[0]?.id ?? null;
-}
-/**
- * Cheap liveness probe for an EvalRunStatus. A `run.json` can be stale
- * (process crashed mid-commit), so we double-check with `kill(pid, 0)`
- * before trusting the `state: "running"` field.
- */
-export function isRunAlive(status) {
-    if (status.state !== "running")
-        return false;
-    try {
-        process.kill(status.pid, 0);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}

package/dist/eval/sandbox.d.ts

@@ -1,38 +0,0 @@
-export declare class SandboxEscapeError extends Error {
-    readonly requestedPath: string;
-    constructor(requestedPath: string, reason: string);
-}
-export interface SandboxOptions {
-    /** Project root that `contextFiles` are resolved against. */
-    projectRoot: string;
-    /** Case-relative paths to copy into the sandbox before the agent starts. */
-    contextFiles?: string[];
-    /**
-     * Base directory that will host the per-case tmpdir. Defaults to
-     * `os.tmpdir()`. Tests inject a repo-local path so CI leaves no
-     * traces in `/tmp` when assertions fail.
-     */
-    baseDir?: string;
-    /** Override the per-case suffix. Primarily for deterministic tests. */
-    idOverride?: string;
-}
-export interface Sandbox {
-    /** Absolute path to the sandbox root directory. */
-    root: string;
-    /**
-     * Resolve `requested` relative to the sandbox root and return the
-     * absolute, realpath'd filesystem path. Throws
-     * `SandboxEscapeError` when the resolution crosses the boundary.
-     *
-     * `allowMissing: true` lets callers pre-resolve a destination for a
-     * write where the final component doesn't exist yet — the parent
-     * directory is realpath'd to still catch symlink escapes.
-     */
-    resolve(requested: string, options?: {
-        allowMissing?: boolean;
-    }): Promise<string>;
-    /** Remove the sandbox directory. Idempotent. */
-    dispose(): Promise<void>;
-}
-/** Create and prep a fresh sandbox. Callers own cleanup via `dispose()`. */
-export declare function createSandbox(options: SandboxOptions): Promise<Sandbox>;

package/dist/eval/sandbox.js

@@ -1,137 +0,0 @@
-/**
- * Per-case sandbox for the with-tools agent (agent/workflow mode).
- *
- * Every case gets its own `os.tmpdir()/cclaw-eval-<uuid>/` directory. Any
- * `contextFiles` the case declares are copied in relative to the project
- * root, and every tool invocation resolves paths against the sandbox
- * root with a defensive check that refuses symlinks and `..` escapes.
- *
- * Design notes:
- *
- * - The sandbox is intentionally tiny (one directory, no symlink
- *   creation, no executable bits). We rely on `fs.realpath` on every
- *   resolved path so hostile tool output that creates a symlink to
- *   `/etc/passwd` and then tries to read it still trips the boundary
- *   check.
- * - Cleanup is handled by `dispose()`; callers (runner, tests) must
- *   invoke it in a `try/finally` so leftover temp directories never
- *   accumulate.
- * - The sandbox does not preserve the project's directory structure
- *   verbatim. Each entry in `contextFiles` is copied flat into
- *   `sandboxRoot/<basename>` unless it contains path separators, in
- *   which case the full relative layout is recreated. That keeps demo
- *   cases portable while still letting richer cases place files under
- *   subdirectories (e.g. `.cclaw/skills/brainstorming/SKILL.md`).
- */
-import { randomUUID } from "node:crypto";
-import fs from "node:fs/promises";
-import os from "node:os";
-import path from "node:path";
-export class SandboxEscapeError extends Error {
-    requestedPath;
-    constructor(requestedPath, reason) {
-        super(`Sandbox refused path "${requestedPath}": ${reason}.`);
-        this.name = "SandboxEscapeError";
-        this.requestedPath = requestedPath;
-    }
-}
-/** Create and prep a fresh sandbox. Callers own cleanup via `dispose()`. */
-export async function createSandbox(options) {
-    const baseDir = options.baseDir ?? os.tmpdir();
-    const id = options.idOverride ?? randomUUID();
-    const root = path.join(baseDir, `cclaw-eval-${id}`);
-    await fs.mkdir(root, { recursive: true });
-    const realRoot = await fs.realpath(root);
-    if (options.contextFiles && options.contextFiles.length > 0) {
-        for (const rel of options.contextFiles) {
-            await copyContextFile(options.projectRoot, realRoot, rel);
-        }
-    }
-    async function resolveInside(requested, opts = {}) {
-        if (typeof requested !== "string" || requested.length === 0) {
-            throw new SandboxEscapeError(String(requested), "path must be a non-empty string");
-        }
-        if (path.isAbsolute(requested)) {
-            throw new SandboxEscapeError(requested, "absolute paths are not allowed");
-        }
-        if (requested.includes("\0")) {
-            throw new SandboxEscapeError(requested, "NUL byte in path");
-        }
-        const joined = path.resolve(realRoot, requested);
-        const relative = path.relative(realRoot, joined);
-        if (relative.startsWith("..") || path.isAbsolute(relative)) {
-            throw new SandboxEscapeError(requested, "resolves outside the sandbox");
-        }
-        let finalPath;
-        try {
-            finalPath = await fs.realpath(joined);
-        }
-        catch (err) {
-            if (!opts.allowMissing) {
-                throw new SandboxEscapeError(requested, `realpath failed: ${err.message}`);
-            }
-            const existingAncestor = await findExistingAncestor(joined, realRoot);
-            if (!existingAncestor) {
-                throw new SandboxEscapeError(requested, "no existing ancestor inside the sandbox");
-            }
-            const ancestorRel = path.relative(realRoot, existingAncestor.real);
-            if (ancestorRel.startsWith("..") || path.isAbsolute(ancestorRel)) {
-                throw new SandboxEscapeError(requested, "parent resolves outside the sandbox");
-            }
-            finalPath = path.join(existingAncestor.real, existingAncestor.trailing);
-        }
-        const finalRel = path.relative(realRoot, finalPath);
-        if (finalRel.startsWith("..") || path.isAbsolute(finalRel)) {
-            throw new SandboxEscapeError(requested, "realpath escapes the sandbox");
-        }
-        return finalPath;
-    }
-    return {
-        root: realRoot,
-        resolve: resolveInside,
-        async dispose() {
-            await fs.rm(realRoot, { recursive: true, force: true });
-        }
-    };
-}
-async function findExistingAncestor(target, stopAt) {
-    const segments = [];
-    let current = target;
-    while (true) {
-        try {
-            const real = await fs.realpath(current);
-            return { real, trailing: path.join(...segments.reverse()) };
-        }
-        catch {
-            const parent = path.dirname(current);
-            if (parent === current)
-                return undefined;
-            segments.push(path.basename(current));
-            if (path.relative(stopAt, parent).startsWith(".."))
-                return undefined;
-            current = parent;
-        }
-    }
-}
-async function copyContextFile(projectRoot, sandboxRoot, relPath) {
-    if (path.isAbsolute(relPath)) {
-        throw new Error(`context_files must be project-relative: ${relPath}`);
-    }
-    const src = path.resolve(projectRoot, relPath);
-    const srcReal = await fs.realpath(src);
-    const projectReal = await fs.realpath(projectRoot);
-    const inside = path.relative(projectReal, srcReal);
-    if (inside.startsWith("..") || path.isAbsolute(inside)) {
-        throw new Error(`context_files entry resolves outside the project: ${relPath}`);
-    }
-    const stat = await fs.stat(srcReal);
-    if (stat.isDirectory()) {
-        const dest = path.join(sandboxRoot, relPath);
-        await fs.mkdir(dest, { recursive: true });
-        await fs.cp(srcReal, dest, { recursive: true });
-        return;
-    }
-    const dest = path.join(sandboxRoot, relPath);
-    await fs.mkdir(path.dirname(dest), { recursive: true });
-    await fs.copyFile(srcReal, dest);
-}

package/dist/eval/tools/glob.d.ts

@@ -1,2 +0,0 @@
-import { type SandboxTool } from "./types.js";
-export declare const globTool: SandboxTool;

package/dist/eval/tools/glob.js

@@ -1,163 +0,0 @@
-import fs from "node:fs/promises";
-import path from "node:path";
-import { SandboxEscapeError } from "../sandbox.js";
-import { parseArgs, requireString, truncatePayload } from "./types.js";
-const DESCRIPTION = "List files inside the sandbox whose relative path matches a glob-style " +
-    "pattern. Supports `*` (any chars within a path segment) and `**` " +
-    "(any number of path segments). Returns matching paths, one per line.";
-const MAX_MATCHES = 500;
-export const globTool = {
-    descriptor: {
-        name: "glob",
-        description: DESCRIPTION,
-        parameters: {
-            type: "object",
-            additionalProperties: false,
-            required: ["pattern"],
-            properties: {
-                pattern: {
-                    type: "string",
-                    description: "Glob pattern, relative to the sandbox root."
-                }
-            }
-        }
-    },
-    async invoke(rawArgs, ctx) {
-        let args;
-        try {
-            args = parseArgs(rawArgs);
-        }
-        catch (err) {
-            return { ok: false, name: this.descriptor.name, error: err.message };
-        }
-        let pattern;
-        try {
-            pattern = requireString(args, "pattern");
-        }
-        catch (err) {
-            return { ok: false, name: this.descriptor.name, error: err.message };
-        }
-        if (pattern.includes("\0")) {
-            return {
-                ok: false,
-                name: this.descriptor.name,
-                error: '"pattern" must not contain NUL bytes'
-            };
-        }
-        let regex;
-        try {
-            regex = globToRegExp(pattern);
-        }
-        catch (err) {
-            return {
-                ok: false,
-                name: this.descriptor.name,
-                error: err.message
-            };
-        }
-        const matches = [];
-        try {
-            await walk(ctx.sandbox.root, "", matches, regex);
-        }
-        catch (err) {
-            if (err instanceof SandboxEscapeError) {
-                return {
-                    ok: false,
-                    name: this.descriptor.name,
-                    error: err.message,
-                    details: { deniedPath: pattern }
-                };
-            }
-            return {
-                ok: false,
-                name: this.descriptor.name,
-                error: `walk failed: ${err.message}`
-            };
-        }
-        matches.sort();
-        const capped = matches.slice(0, MAX_MATCHES);
-        const body = capped.length > 0
-            ? capped.join("\n") +
-                (matches.length > capped.length
-                    ? `\n…[truncated at ${MAX_MATCHES} matches]`
-                    : "")
-            : "(no matches)";
-        return {
-            ok: true,
-            name: this.descriptor.name,
-            content: truncatePayload(body, ctx.maxResultBytes),
-            details: {
-                pattern,
-                matches: capped.length,
-                totalMatches: matches.length,
-                truncated: matches.length > capped.length
-            }
-        };
-    }
-};
-async function walk(root, rel, acc, regex) {
-    const dir = path.join(root, rel);
-    let entries;
-    try {
-        entries = (await fs.readdir(dir, { withFileTypes: true }));
-    }
-    catch {
-        return;
-    }
-    for (const entry of entries) {
-        const childRel = rel ? path.join(rel, entry.name) : entry.name;
-        if (entry.isSymbolicLink())
-            continue;
-        if (entry.isDirectory()) {
-            await walk(root, childRel, acc, regex);
-            continue;
-        }
-        if (entry.isFile() && regex.test(childRel.replace(/\\/g, "/"))) {
-            acc.push(childRel);
-        }
-    }
-}
-/**
- * Minimal glob → regex: `**` matches zero or more path segments, `*`
- * matches anything except `/`, `?` matches a single non-slash char.
- * Everything else is escaped. Intentionally narrower than full
- * bash-style expansion so behavior is easy to reason about.
- */
-function globToRegExp(pattern) {
-    const normalized = pattern.replace(/\\/g, "/");
-    let src = "^";
-    let i = 0;
-    while (i < normalized.length) {
-        const c = normalized[i];
-        if (c === "*") {
-            if (normalized[i + 1] === "*") {
-                if (normalized[i + 2] === "/") {
-                    src += "(?:.*/)?";
-                    i += 3;
-                }
-                else {
-                    src += ".*";
-                    i += 2;
-                }
-            }
-            else {
-                src += "[^/]*";
-                i += 1;
-            }
-        }
-        else if (c === "?") {
-            src += "[^/]";
-            i += 1;
-        }
-        else if ("+()|^$.{}[]\\".includes(c)) {
-            src += `\\${c}`;
-            i += 1;
-        }
-        else {
-            src += c;
-            i += 1;
-        }
-    }
-    src += "$";
-    return new RegExp(src);
-}

package/dist/eval/tools/grep.d.ts

@@ -1,2 +0,0 @@
-import { type SandboxTool } from "./types.js";
-export declare const grepTool: SandboxTool;

package/dist/eval/tools/grep.js

@@ -1,152 +0,0 @@
-import fs from "node:fs/promises";
-import path from "node:path";
-import { SandboxEscapeError } from "../sandbox.js";
-import { parseArgs, requireString, optionalNumber, truncatePayload } from "./types.js";
-const DESCRIPTION = "Search the sandbox for a regular expression. Returns matching lines in " +
-    "`path:line:text` form. Accepts optional `caseInsensitive` and a per-call " +
-    "`maxMatches` cap (default 100, hard max 500).";
-const HARD_MAX = 500;
-export const grepTool = {
-    descriptor: {
-        name: "grep",
-        description: DESCRIPTION,
-        parameters: {
-            type: "object",
-            additionalProperties: false,
-            required: ["pattern"],
-            properties: {
-                pattern: {
-                    type: "string",
-                    description: "Regular expression compiled with JavaScript semantics."
-                },
-                caseInsensitive: {
-                    type: "boolean",
-                    description: "Match case-insensitively (default false)."
-                },
-                maxMatches: {
-                    type: "integer",
-                    minimum: 1,
-                    description: "Stop after N matches (default 100, hard max 500)."
-                }
-            }
-        }
-    },
-    async invoke(rawArgs, ctx) {
-        let args;
-        try {
-            args = parseArgs(rawArgs);
-        }
-        catch (err) {
-            return { ok: false, name: this.descriptor.name, error: err.message };
-        }
-        let pattern;
-        try {
-            pattern = requireString(args, "pattern");
-        }
-        catch (err) {
-            return { ok: false, name: this.descriptor.name, error: err.message };
-        }
-        const caseInsensitive = args.caseInsensitive === true;
-        let maxMatches;
-        try {
-            const raw = optionalNumber(args, "maxMatches");
-            maxMatches = raw === undefined ? 100 : Math.min(HARD_MAX, Math.max(1, Math.floor(raw)));
-        }
-        catch (err) {
-            return {
-                ok: false,
-                name: this.descriptor.name,
-                error: err.message
-            };
-        }
-        let regex;
-        try {
-            regex = new RegExp(pattern, caseInsensitive ? "i" : "");
-        }
-        catch (err) {
-            return {
-                ok: false,
-                name: this.descriptor.name,
-                error: `invalid regex: ${err.message}`
-            };
-        }
-        let filesScanned = 0;
-        const hits = [];
-        try {
-            await walk(ctx.sandbox.root, "", async (relPath, abs) => {
-                if (hits.length >= maxMatches)
-                    return false;
-                let content;
-                try {
-                    content = await fs.readFile(abs, "utf8");
-                }
-                catch {
-                    return true;
-                }
-                filesScanned += 1;
-                const lines = content.split(/\r?\n/);
-                for (let i = 0; i < lines.length; i += 1) {
-                    const line = lines[i];
-                    if (regex.test(line)) {
-                        hits.push(`${relPath}:${i + 1}:${line}`);
-                        if (hits.length >= maxMatches)
-                            return false;
-                    }
-                }
-                return true;
-            });
-        }
-        catch (err) {
-            if (err instanceof SandboxEscapeError) {
-                return {
-                    ok: false,
-                    name: this.descriptor.name,
-                    error: err.message,
-                    details: { deniedPath: pattern }
-                };
-            }
-            return {
-                ok: false,
-                name: this.descriptor.name,
-                error: `walk failed: ${err.message}`
-            };
-        }
-        const body = hits.length > 0 ? hits.join("\n") : "(no matches)";
-        return {
-            ok: true,
-            name: this.descriptor.name,
-            content: truncatePayload(body, ctx.maxResultBytes),
-            details: {
-                pattern,
-                caseInsensitive,
-                matches: hits.length,
-                filesScanned,
-                truncated: hits.length >= maxMatches
-            }
-        };
-    }
-};
-async function walk(root, rel, visit) {
-    const dir = path.join(root, rel);
-    let entries;
-    try {
-        entries = (await fs.readdir(dir, { withFileTypes: true }));
-    }
-    catch {
-        return;
-    }
-    for (const entry of entries) {
-        const childRel = rel ? path.join(rel, entry.name) : entry.name;
-        if (entry.isSymbolicLink())
-            continue;
-        if (entry.isDirectory()) {
-            await walk(root, childRel, visit);
-            continue;
-        }
-        if (entry.isFile()) {
-            const keepGoing = await visit(childRel.replace(/\\/g, "/"), path.join(root, childRel));
-            if (keepGoing === false)
-                return;
-        }
-    }
-}

package/dist/eval/tools/index.d.ts

@@ -1,7 +0,0 @@
-import type { SandboxTool } from "./types.js";
-export { SandboxTool, ToolResult, ToolContext, truncatePayload } from "./types.js";
-export declare const BUILTIN_TOOLS: SandboxTool[];
-/** Build a lookup for the agent loop. */
-export declare function toolsByName(tools?: SandboxTool[]): Map<string, SandboxTool>;
-/** Shape a tool list for OpenAI-style `tools[]` in the chat request. */
-export declare function toolsForRequest(tools?: SandboxTool[]): unknown[];