profclaw 2.0.0 → 2.4.0

package/dist/agents/verifier.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Verifier
+ *
+ * Runs a user-provided verification command (tests, typecheck, lint, build or
+ * anything custom) as an objective judge of "done". The command is the only
+ * shell input: goal text and model output are never interpolated into it.
+ *
+ * Safety conventions:
+ *  - runs with cwd pinned to the run's worktree
+ *  - hard timeout, process group is killed on expiry
+ *  - captured output is capped in memory and trimmed for feedback
+ *  - a small denylist rejects commands that publish or destroy (git push,
+ *    gh pr create, rm -rf /, curl | sh) because a verifier must only observe
+ */
+import type { PlanOptions } from './command-sandbox.js';
+export interface VerifierResult {
+    passed: boolean;
+    /** Exit code, or null when killed by timeout or signal */
+    exitCode: number | null;
+    timedOut: boolean;
+    durationMs: number;
+    /** Trimmed combined stdout + stderr, suitable for feeding back to an agent */
+    output: string;
+    /** True when the raw output was longer than the trimmed output */
+    truncated: boolean;
+}
+export interface VerifierOptions {
+    cwd: string;
+    timeoutMs: number;
+    /** Max characters of output kept for feedback (head and tail are kept) */
+    maxOutputChars: number;
+    env?: NodeJS.ProcessEnv;
+    /**
+     * Run the command under the OS sandbox (see command-sandbox.ts). Off by
+     * default: user supplied verify commands often need network or write
+     * outside the worktree (package caches).
+     */
+    sandbox?: PlanOptions & {
+        allowNetwork?: boolean;
+    };
+}
+/** Anything that can judge a workspace. Tests inject fakes. */
+export interface Verifier {
+    verify(): Promise<VerifierResult>;
+}
+/** Returns a rejection reason, or null when the command is acceptable. */
+export declare function validateVerifyCommand(command: string): string | null;
+/**
+ * Keep the head and tail of long output (failures usually name the problem
+ * at the top and summarise at the bottom) and drop the middle.
+ */
+export declare function trimOutput(raw: string, maxChars: number): {
+    text: string;
+    truncated: boolean;
+};
+export declare class CommandVerifier implements Verifier {
+    private readonly command;
+    private readonly options;
+    constructor(command: string, options: VerifierOptions);
+    verify(): Promise<VerifierResult>;
+}
+/** Format a result as feedback text for the next agent attempt. */
+export declare function formatFailureFeedback(result: VerifierResult, command: string): string;
+//# sourceMappingURL=verifier.d.ts.map

package/dist/agents/verifier.js

@@ -0,0 +1,186 @@
+/**
+ * Verifier
+ *
+ * Runs a user-provided verification command (tests, typecheck, lint, build or
+ * anything custom) as an objective judge of "done". The command is the only
+ * shell input: goal text and model output are never interpolated into it.
+ *
+ * Safety conventions:
+ *  - runs with cwd pinned to the run's worktree
+ *  - hard timeout, process group is killed on expiry
+ *  - captured output is capped in memory and trimmed for feedback
+ *  - a small denylist rejects commands that publish or destroy (git push,
+ *    gh pr create, rm -rf /, curl | sh) because a verifier must only observe
+ */
+import { spawn } from 'node:child_process';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { planSandboxedCommand, resolveAllowNetwork, resolveExtraWritable } from './command-sandbox.js';
+// Command policy
+const FORBIDDEN_PATTERNS = [
+    { pattern: /\bgit\b[^;&|\n]*\bpush\b/, reason: 'git push is not allowed in a verifier' },
+    { pattern: /\bgh\s+pr\s+(?:create|merge)\b/, reason: 'opening or merging PRs is not allowed in a verifier' },
+    { pattern: /\brm\s+(?:-\S*\s+)*-\S*[rR]\S*\s+(?:-\S+\s+)*(?:\/|~|\$HOME)(?:\s|$)/, reason: 'destructive rm is not allowed in a verifier' },
+    { pattern: /\b(?:curl|wget)\b[^|;&]*\|\s*(?:sudo\s+)?(?:sh|bash|zsh)\b/, reason: 'piping downloads into a shell is not allowed' },
+    { pattern: /\bsudo\b/, reason: 'sudo is not allowed in a verifier' },
+];
+/** Returns a rejection reason, or null when the command is acceptable. */
+export function validateVerifyCommand(command) {
+    if (command.trim().length === 0)
+        return 'verify command is empty';
+    if (command.includes('\0'))
+        return 'verify command contains a NUL byte';
+    for (const { pattern, reason } of FORBIDDEN_PATTERNS) {
+        if (pattern.test(command))
+            return reason;
+    }
+    return null;
+}
+// Output trimming
+/**
+ * Keep the head and tail of long output (failures usually name the problem
+ * at the top and summarise at the bottom) and drop the middle.
+ */
+export function trimOutput(raw, maxChars) {
+    const cleaned = stripAnsi(raw).trim();
+    if (cleaned.length <= maxChars)
+        return { text: cleaned, truncated: false };
+    const marker = '\n... [output trimmed] ...\n';
+    const budget = Math.max(0, maxChars - marker.length);
+    const head = Math.ceil(budget * 0.4);
+    const tail = budget - head;
+    return {
+        text: cleaned.slice(0, head) + marker + (tail > 0 ? cleaned.slice(-tail) : ''),
+        truncated: true,
+    };
+}
+function stripAnsi(text) {
+    // eslint-disable-next-line no-control-regex
+    return text.replace(/\u001b\[[0-9;?]*[ -/]*[@-~]/g, '');
+}
+// Command verifier
+export class CommandVerifier {
+    command;
+    options;
+    constructor(command, options) {
+        this.command = command;
+        this.options = options;
+    }
+    async verify() {
+        const rejection = validateVerifyCommand(this.command);
+        if (rejection) {
+            return {
+                passed: false,
+                exitCode: null,
+                timedOut: false,
+                durationMs: 0,
+                output: `Verifier rejected: ${rejection}`,
+                truncated: false,
+            };
+        }
+        return runCommand(this.command, this.options);
+    }
+}
+// Cap on raw bytes retained in memory regardless of trim setting.
+const RAW_CAPTURE_LIMIT = 2_000_000;
+async function runCommand(command, options) {
+    if (!options.sandbox)
+        return spawnCommand({ file: '/bin/sh', args: ['-c', command], env: {}, backend: 'none' }, options);
+    const tempDir = await mkdtemp(join(tmpdir(), 'profclaw-verify-'));
+    try {
+        const plan = planSandboxedCommand(command, {
+            workdir: options.cwd,
+            tempDir,
+            allowNetwork: options.sandbox.allowNetwork ?? resolveAllowNetwork(),
+            extraWritable: resolveExtraWritable(),
+        }, options.sandbox);
+        return await spawnCommand(plan, options);
+    }
+    catch (error) {
+        return {
+            passed: false,
+            exitCode: null,
+            timedOut: false,
+            durationMs: 0,
+            output: `Verifier sandbox error: ${error instanceof Error ? error.message : String(error)}`,
+            truncated: false,
+        };
+    }
+    finally {
+        await rm(tempDir, { recursive: true, force: true });
+    }
+}
+function spawnCommand(plan, options) {
+    return new Promise((resolve) => {
+        const started = Date.now();
+        let buffer = '';
+        let rawTruncated = false;
+        let timedOut = false;
+        let settled = false;
+        const child = spawn(plan.file, plan.args, {
+            cwd: options.cwd,
+            env: { ...process.env, ...options.env, ...plan.env, CI: process.env.CI ?? '1' },
+            stdio: ['ignore', 'pipe', 'pipe'],
+            detached: true,
+        });
+        const append = (chunk) => {
+            if (buffer.length >= RAW_CAPTURE_LIMIT) {
+                rawTruncated = true;
+                return;
+            }
+            buffer += chunk.toString('utf-8');
+        };
+        child.stdout.on('data', append);
+        child.stderr.on('data', append);
+        const killGroup = () => {
+            if (child.pid === undefined)
+                return;
+            try {
+                process.kill(-child.pid, 'SIGKILL');
+            }
+            catch {
+                child.kill('SIGKILL');
+            }
+        };
+        const timer = setTimeout(() => {
+            timedOut = true;
+            killGroup();
+        }, options.timeoutMs);
+        const finish = (exitCode, extra) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            const trimmed = trimOutput(buffer + (extra ?? ''), options.maxOutputChars);
+            const output = timedOut
+                ? `${trimmed.text}\n[verifier timed out after ${options.timeoutMs}ms]`.trim()
+                : trimmed.text;
+            resolve({
+                passed: exitCode === 0 && !timedOut,
+                exitCode,
+                timedOut,
+                durationMs: Date.now() - started,
+                output,
+                truncated: trimmed.truncated || rawTruncated,
+            });
+        };
+        child.on('error', (err) => finish(null, `\n${err.message}`));
+        child.on('close', (code) => finish(code));
+    });
+}
+/** Format a result as feedback text for the next agent attempt. */
+export function formatFailureFeedback(result, command) {
+    const status = result.timedOut
+        ? 'timed out'
+        : `exited with code ${result.exitCode === null ? 'unknown' : result.exitCode}`;
+    return [
+        `The verification command \`${command}\` ${status}.`,
+        'Output (trimmed):',
+        '```',
+        result.output,
+        '```',
+        'Fix the underlying problem so the command passes. Do not edit the verification command or weaken tests to force a pass.',
+    ].join('\n');
+}
+//# sourceMappingURL=verifier.js.map

package/dist/agents/worktree-manager.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Worktree Manager
+ *
+ * Provides git worktree isolation for agent tasks. Each task can optionally
+ * run in its own git worktree so concurrent agents don't create dirty-tree
+ * conflicts on the main working tree.
+ *
+ * All git operations use execFile (not shell) to avoid injection risks.
+ */
+export interface WorktreeInfo {
+    /** Absolute path to the worktree directory */
+    path: string;
+    /** Branch checked out in this worktree */
+    branch: string;
+    /** Branch the worktree was created from */
+    baseBranch: string;
+    /** Unix timestamp (ms) when this worktree was created */
+    createdAt: number;
+    /** Optional task identifier that owns this worktree */
+    taskId?: string;
+}
+export interface MergeResult {
+    success: boolean;
+    /** Conflicting file paths when success is false */
+    conflicts?: string[];
+}
+export declare class WorktreeManager {
+    private readonly worktrees;
+    /** Absolute path to the directory that holds all created worktrees */
+    private readonly baseDir;
+    /** Resolved project root (the main git working tree) */
+    private readonly projectRoot;
+    constructor(projectRoot?: string);
+    /**
+     * Create an isolated worktree for a task.
+     *
+     * Runs: git worktree add <path> -b <branch> [baseBranch]
+     */
+    create(options: {
+        taskId: string;
+        /** Branch to base the new worktree on (defaults to current HEAD branch) */
+        baseBranch?: string;
+        /** Name for the new branch (defaults to profclaw/task-{taskId}) */
+        branchName?: string;
+    }): Promise<WorktreeInfo>;
+    /** Return all active worktrees tracked by this manager instance. */
+    list(): WorktreeInfo[];
+    /** Return the WorktreeInfo for a specific task, or undefined if unknown. */
+    get(taskId: string): WorktreeInfo | undefined;
+    /**
+     * Merge the worktree's branch back into its base branch.
+     *
+     * Runs: git merge [--squash] <branch>  (executed from the base worktree)
+     */
+    merge(taskId: string, options?: {
+        squash?: boolean;
+        message?: string;
+    }): Promise<MergeResult>;
+    /**
+     * Remove a worktree from disk and deregister it.
+     *
+     * Runs: git worktree remove <path>
+     */
+    remove(taskId: string): Promise<void>;
+    /**
+     * Prune stale worktree metadata that git is tracking but whose paths no
+     * longer exist on disk.
+     *
+     * Runs: git worktree prune
+     *
+     * @returns Number of pruned entries as reported by git
+     */
+    prune(): Promise<number>;
+}
+/**
+ * Return a shared WorktreeManager rooted at the current working directory.
+ * Use the WorktreeManager constructor directly if you need a different root.
+ */
+export declare function getWorktreeManager(): WorktreeManager;
+//# sourceMappingURL=worktree-manager.d.ts.map

package/dist/agents/worktree-manager.js

@@ -0,0 +1,203 @@
+/**
+ * Worktree Manager
+ *
+ * Provides git worktree isolation for agent tasks. Each task can optionally
+ * run in its own git worktree so concurrent agents don't create dirty-tree
+ * conflicts on the main working tree.
+ *
+ * All git operations use execFile (not shell) to avoid injection risks.
+ */
+import { execFile as execFileCb } from "node:child_process";
+import { promisify } from "node:util";
+import { mkdir, rm } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { logger } from '../utils/logger.js';
+const execFile = promisify(execFileCb);
+// Helpers
+function sanitizeBranchName(name) {
+    // Strip characters that are not safe in git branch names
+    return name.replace(/[^a-zA-Z0-9/_.-]/g, "-").replace(/^[-.]|[-.]$/g, "");
+}
+async function getCurrentBranch(cwd) {
+    const { stdout } = await execFile("git", ["rev-parse", "--abbrev-ref", "HEAD"], { cwd });
+    return stdout.trim();
+}
+async function isGitRepo(dir) {
+    try {
+        await execFile("git", ["rev-parse", "--git-dir"], { cwd: dir });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// WorktreeManager
+export class WorktreeManager {
+    worktrees = new Map();
+    /** Absolute path to the directory that holds all created worktrees */
+    baseDir;
+    /** Resolved project root (the main git working tree) */
+    projectRoot;
+    constructor(projectRoot) {
+        this.projectRoot = resolve(projectRoot ?? process.cwd());
+        this.baseDir = join(this.projectRoot, ".profclaw", "worktrees");
+    }
+    /**
+     * Create an isolated worktree for a task.
+     *
+     * Runs: git worktree add <path> -b <branch> [baseBranch]
+     */
+    async create(options) {
+        const { taskId } = options;
+        if (!(await isGitRepo(this.projectRoot))) {
+            throw new Error(`[WorktreeManager] ${this.projectRoot} is not a git repository`);
+        }
+        const baseBranch = options.baseBranch ?? (await getCurrentBranch(this.projectRoot));
+        const rawBranch = options.branchName ?? `profclaw/task-${taskId}`;
+        const branch = sanitizeBranchName(rawBranch);
+        const worktreePath = join(this.baseDir, taskId);
+        // Ensure the base directory exists
+        await mkdir(this.baseDir, { recursive: true });
+        try {
+            await execFile("git", ["worktree", "add", worktreePath, "-b", branch, baseBranch], { cwd: this.projectRoot });
+        }
+        catch (error) {
+            throw new Error(`[WorktreeManager] Failed to create worktree for task ${taskId}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        const info = {
+            path: worktreePath,
+            branch,
+            baseBranch,
+            createdAt: Date.now(),
+            taskId,
+        };
+        this.worktrees.set(taskId, info);
+        logger.info(`[WorktreeManager] Created worktree for task ${taskId} at ${worktreePath}`);
+        return info;
+    }
+    /** Return all active worktrees tracked by this manager instance. */
+    list() {
+        return Array.from(this.worktrees.values());
+    }
+    /** Return the WorktreeInfo for a specific task, or undefined if unknown. */
+    get(taskId) {
+        return this.worktrees.get(taskId);
+    }
+    /**
+     * Merge the worktree's branch back into its base branch.
+     *
+     * Runs: git merge [--squash] <branch>  (executed from the base worktree)
+     */
+    async merge(taskId, options) {
+        const info = this.worktrees.get(taskId);
+        if (!info) {
+            throw new Error(`[WorktreeManager] No worktree found for task ${taskId}`);
+        }
+        try {
+            // Ensure we're on the correct base branch before merging
+            await execFile("git", ["checkout", info.baseBranch], {
+                cwd: this.projectRoot,
+            });
+            if (options?.squash) {
+                // Squash merge requires separate commit step
+                await execFile("git", ["merge", "--squash", info.branch], {
+                    cwd: this.projectRoot,
+                });
+                const commitMsg = options.message || `Squash merge branch '${info.branch}'`;
+                await execFile("git", ["commit", "-m", commitMsg], {
+                    cwd: this.projectRoot,
+                });
+            }
+            else {
+                const mergeArgs = ["merge", info.branch];
+                if (options?.message) {
+                    mergeArgs.push("-m", options.message);
+                }
+                await execFile("git", mergeArgs, { cwd: this.projectRoot });
+            }
+            logger.info(`[WorktreeManager] Merged branch ${info.branch} into ${info.baseBranch}`);
+            return { success: true };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            // Extract conflicting file names from git's error/stdout output
+            const conflicts = message
+                .split("\n")
+                .filter((line) => line.startsWith("CONFLICT"))
+                .map((line) => line.replace(/^CONFLICT[^:]*:\s*/i, "").trim())
+                .filter(Boolean);
+            logger.error(`[WorktreeManager] Merge conflicts for task ${taskId}:`, error instanceof Error ? error : new Error(String(error)));
+            return { success: false, conflicts };
+        }
+    }
+    /**
+     * Remove a worktree from disk and deregister it.
+     *
+     * Runs: git worktree remove <path>
+     */
+    async remove(taskId) {
+        const info = this.worktrees.get(taskId);
+        if (!info) {
+            throw new Error(`[WorktreeManager] No worktree found for task ${taskId}`);
+        }
+        try {
+            await execFile("git", ["worktree", "remove", info.path, "--force"], {
+                cwd: this.projectRoot,
+            });
+        }
+        catch (error) {
+            // If git worktree remove fails (e.g. path already gone) try to clean up
+            // the directory ourselves so we stay consistent.
+            logger.error(`[WorktreeManager] git worktree remove failed for task ${taskId}, attempting manual rm:`, error instanceof Error ? error : new Error(String(error)));
+            try {
+                await rm(info.path, { recursive: true, force: true });
+            }
+            catch (rmError) {
+                logger.error(`[WorktreeManager] Manual rm also failed for ${info.path}:`, rmError instanceof Error ? rmError : new Error(String(rmError)));
+            }
+        }
+        this.worktrees.delete(taskId);
+        logger.info(`[WorktreeManager] Removed worktree for task ${taskId}`);
+    }
+    /**
+     * Prune stale worktree metadata that git is tracking but whose paths no
+     * longer exist on disk.
+     *
+     * Runs: git worktree prune
+     *
+     * @returns Number of pruned entries as reported by git
+     */
+    async prune() {
+        if (!(await isGitRepo(this.projectRoot))) {
+            return 0;
+        }
+        try {
+            const { stderr } = await execFile("git", ["worktree", "prune", "--verbose"], { cwd: this.projectRoot });
+            // git prints one line per pruned entry to stderr when --verbose is given
+            const pruned = stderr
+                .split("\n")
+                .filter((line) => line.trim().length > 0).length;
+            if (pruned > 0) {
+                logger.info(`[WorktreeManager] Pruned ${pruned} stale worktree(s)`);
+            }
+            return pruned;
+        }
+        catch (error) {
+            logger.error(`[WorktreeManager] Failed to prune worktrees:`, error instanceof Error ? error : new Error(String(error)));
+            return 0;
+        }
+    }
+}
+// Singleton
+let _manager;
+/**
+ * Return a shared WorktreeManager rooted at the current working directory.
+ * Use the WorktreeManager constructor directly if you need a different root.
+ */
+export function getWorktreeManager() {
+    if (!_manager) {
+        _manager = new WorktreeManager();
+    }
+    return _manager;
+}
+//# sourceMappingURL=worktree-manager.js.map

package/dist/agents/worktree-tools.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Worktree-confined tools for the verified-run agent.
+ *
+ * A small coding toolset (read, write, list, shell, complete) whose every file
+ * operation is resolved against a single root directory, the run's git
+ * worktree. Paths that escape the root (via `..`, absolute paths or symlinks)
+ * are rejected, writes into `.git` are refused, and shell commands that push
+ * or open pull requests are denied. Cautious and dangerous tools also go
+ * through the existing PermissionManager (src/agents/permissions.ts).
+ *
+ * The shell tool runs with the worktree as cwd and a scrubbed environment,
+ * confined by an OS sandbox when available (src/agents/command-sandbox.ts).
+ * Without one it falls back to pattern screening, a guard rail, not a jail.
+ */
+import type { ToolSet } from 'ai';
+import { PermissionManager } from './permissions.js';
+import type { ToolExecuteHandler } from './executor.js';
+import type { PlanOptions } from './command-sandbox.js';
+export interface WorktreeToolsOptions {
+    /** Root every file operation is confined to */
+    workdir: string;
+    permissions?: PermissionManager;
+    /** Kill shell commands after this long */
+    commandTimeoutMs: number;
+    /** Cap on text returned to the model per tool call */
+    maxOutputChars: number;
+    /** Sandbox overrides (mode, availability check); defaults come from PROFCLAW_RUN_SANDBOX */
+    sandbox?: PlanOptions;
+    /** Override PROFCLAW_RUN_ALLOW_NETWORK */
+    allowNetwork?: boolean;
+}
+export interface WorktreeToolset {
+    tools: ToolSet;
+    execute: ToolExecuteHandler;
+    /** Remove the per-run sandbox temp dir */
+    dispose: () => Promise<void>;
+}
+export declare function isBlockedCommand(command: string): boolean;
+/** Non-interactive policy: allow everything except publishing actions. */
+export declare function createRunPermissionManager(): PermissionManager;
+/**
+ * Resolve `requested` against `root` and guarantee the result stays inside it,
+ * including through symlinks (checked on the deepest existing ancestor).
+ */
+export declare function confinePath(root: string, requested: string): Promise<string>;
+export declare function createWorktreeToolset(options: WorktreeToolsOptions): WorktreeToolset;
+//# sourceMappingURL=worktree-tools.d.ts.map