@qvac/harness 1.0.0-rc.1 → 1.0.0-rc.2

package/dist-lib/plugins/coding/jobs.js

@@ -0,0 +1,144 @@
+import { capped, errorText, guidance } from './session.js';
+const MAX_JOBS = 4;
+export class Jobs {
+    _session;
+    _jobs;
+    _next;
+    constructor(session) {
+        this._session = session;
+        this._jobs = new Map();
+        this._next = 0;
+    }
+    _ofRun(runId) {
+        return [...this._jobs.values()].filter((job) => job.runId === runId);
+    }
+    async start(call) {
+        const { workspace, runId, line: command } = call;
+        const running = this._ofRun(runId).filter((job) => job.status === 'running');
+        if (running.length >= MAX_JOBS) {
+            return guidance(`this run already has ${MAX_JOBS} running jobs; stop one with shell_jobs first`);
+        }
+        const id = `job-${++this._next}`;
+        const handle = await this._session.start(call, id);
+        const job = { id, runId, command, handle, workspace, status: 'running' };
+        this._jobs.set(id, job);
+        void handle.exited.then((code) => {
+            if (job.status === 'running') {
+                job.status = 'exited';
+                job.exitCode = code;
+            }
+        });
+        return { job: id, status: 'running', note: 'read it with shell_jobs action=output' };
+    }
+    async _stop(jobs) {
+        const live = jobs.filter((job) => job.status === 'running');
+        for (const job of live) {
+            job.status = 'stopped';
+        }
+        await Promise.allSettled(live.map((job) => job.handle.stop()));
+    }
+    _find(runId, id) {
+        const job = typeof id === 'string' ? this._jobs.get(id) : undefined;
+        return job && job.runId === runId ? job : guidance(`no job ${String(id)} in this run`);
+    }
+    list(runId) {
+        const jobs = this._ofRun(runId);
+        return {
+            jobs: jobs.map(({ id, command, status, exitCode }) => ({ id, command, status, exitCode }))
+        };
+    }
+    async output(read, ctx) {
+        const { since } = read;
+        const job = this._find(read.runId, read.id);
+        if ('error' in job) {
+            return job;
+        }
+        const log = this._session.jobLog(job.id);
+        const { stdout } = await this._session.execState(job.workspace, `n=$(wc -c < ${log} | tr -d ' '); echo "$n"; tail -c +${since + 1} ${log} | head -c $((n > ${since} ? n - ${since} : 0))`);
+        const cut = stdout.indexOf('\n');
+        const size = Number.parseInt(stdout.slice(0, cut), 10);
+        return {
+            output: await capped(stdout.slice(cut + 1), 'stdout', ctx),
+            next: Number.isSafeInteger(size) ? Math.max(size, since) : since,
+            status: job.status,
+            exitCode: job.exitCode
+        };
+    }
+    async stop(runId, id) {
+        const job = this._find(runId, id);
+        if ('error' in job) {
+            return job;
+        }
+        await this._stop([job]);
+        return { job: job.id, status: job.status };
+    }
+    async endRun(runId) {
+        const jobs = this._ofRun(runId);
+        await this._stop(jobs);
+        for (const job of jobs) {
+            this._jobs.delete(job.id);
+        }
+    }
+    async close() {
+        await this._stop([...this._jobs.values()]);
+        this._jobs.clear();
+    }
+}
+const ACTIONS = ['list', 'output', 'stop'];
+const JOBS_PARAMETERS = {
+    type: 'object',
+    properties: {
+        action: { type: 'string', enum: ACTIONS },
+        id: { type: 'string', description: 'The job id shell returned' },
+        since: { type: 'integer', description: 'Log offset to read from; default 0' }
+    },
+    required: ['action']
+};
+function invalid(args) {
+    if (!ACTIONS.some((action) => action === args.action)) {
+        return `action must be one of ${ACTIONS.join(', ')}`;
+    }
+    if (args.action !== 'list' && typeof args.id !== 'string') {
+        return `${String(args.action)} needs the job id`;
+    }
+    const { since } = args;
+    return since === undefined || (Number.isSafeInteger(since) && Number(since) >= 0)
+        ? null
+        : 'since must be a non-negative integer';
+}
+function runJobs(jobs, args, ctx) {
+    const runId = ctx?.runId ?? '';
+    if (args.action === 'list') {
+        return Promise.resolve(jobs.list(runId));
+    }
+    if (args.action === 'stop') {
+        return jobs.stop(runId, args.id);
+    }
+    const since = Number.isSafeInteger(args.since) ? Number(args.since) : 0;
+    return jobs.output({ runId, id: args.id, since }, ctx);
+}
+export function shellJobsTool(session, jobs) {
+    return {
+        name: 'shell_jobs',
+        toolset: 'coding',
+        policyVersion: session.policyVersion(),
+        description: 'List, read or stop the jobs shell started with background. output returns the log ' +
+            'from the since offset and the offset to ask from next time. Jobs stop when the run ends.',
+        parameters: JOBS_PARAMETERS,
+        effect: (_args, ctx) => session.effect(ctx),
+        quote: (args) => [args.action, args.id].filter((part) => typeof part === 'string').join(' '),
+        validate: invalid,
+        async execute(args, ctx) {
+            const refused = session.refusal(ctx);
+            if (refused) {
+                return refused;
+            }
+            try {
+                return await runJobs(jobs, args, ctx);
+            }
+            catch (error) {
+                return { error: errorText(error) };
+            }
+        }
+    };
+}

package/dist-lib/plugins/coding/session.d.ts

@@ -0,0 +1,51 @@
+import type { AbortSignal as BareAbortSignal } from 'bare-abort-controller';
+import type { ToolDefinition, ToolExecuteContext } from '../../lib/contract/index.ts';
+import type { SandboxExecResult, SandboxJob, SandboxService, SandboxWorkspace } from '../../lib/contract/sandbox.ts';
+import { type LocalRoot } from '../../lib/tools/fs/scope.ts';
+export interface ToolError {
+    error: string;
+    guidance?: true;
+}
+export declare function guidance(error: string): ToolError;
+export declare function isError(value: unknown): value is ToolError;
+export declare function shellQuote(text: string): string;
+export declare function errorText(error: unknown): string;
+export declare function workspaceKey(root: LocalRoot, input: string): Promise<string | ToolError>;
+export declare function capped(text: string, stream: 'stdout' | 'stderr', ctx: ToolExecuteContext | undefined): Promise<string>;
+interface ExecCall {
+    timeoutMs?: number;
+    signal?: BareAbortSignal | undefined;
+}
+export interface SessionLine {
+    workspace: SandboxWorkspace;
+    runId: string;
+    line: string;
+}
+export declare class CodingSession {
+    readonly sandbox: SandboxService;
+    readonly deniedRoots: readonly string[];
+    private readonly _bind;
+    private readonly _workspaces;
+    private readonly _runs;
+    constructor(sandbox: SandboxService, deniedRoots?: readonly string[]);
+    effect(ctx: ToolExecuteContext | undefined): 'read' | 'write';
+    refusal(ctx: ToolExecuteContext | undefined): ToolError | null;
+    workspace(ctx: ToolExecuteContext | undefined): Promise<LocalRoot | ToolError>;
+    policyVersion(): string;
+    statePath(runId: string): string;
+    open(root: LocalRoot, runId: string): Promise<SandboxWorkspace>;
+    workspaceOf(runId: string): Promise<SandboxWorkspace> | null;
+    private _prelude;
+    exec({ workspace, runId, line }: SessionLine, { timeoutMs, signal }?: ExecCall): Promise<SandboxExecResult>;
+    jobLog(id: string): string;
+    start({ workspace, runId, line }: SessionLine, id: string): Promise<SandboxJob>;
+    execState(workspace: SandboxWorkspace, line: string): Promise<SandboxExecResult>;
+    endRun(runId: string): Promise<void>;
+    close(): Promise<void>;
+}
+export interface ShellToolOptions {
+    session: CodingSession;
+    start(call: SessionLine): Promise<unknown>;
+}
+export declare function shellTool(options: ShellToolOptions): ToolDefinition;
+export {};

package/dist-lib/plugins/coding/session.js

@@ -0,0 +1,263 @@
+import b4a from 'b4a';
+import { randomBytes } from 'crypto';
+import path from 'path';
+import { isRecord } from '../../lib/guards.js';
+import { appendOutput, createCapturedOutput, formatOutput, MAX_OUTPUT_CHARS } from '../../lib/tools/exec/runner.js';
+import { canonicalDenyRoots, defaultRealpath, overlaps, resolveKey } from '../../lib/tools/fs/scope.js';
+const STATE_DIR = '"$__qvac_dir"';
+const SHELL_TIMEOUT_MS = 300_000;
+const MAX_TIMEOUT_MS = 1_800_000;
+const NO_WORKSPACE = 'the coding tools need one writable directory granted to the run, and it has none';
+const DRIVE_WORKSPACE = 'the coding tools work in a local project folder, not a drive or a filesystem root';
+const DENIED_WORKSPACE = 'the coding tools need a project folder that neither holds nor sits in a protected app folder';
+const DRIVE_PATH = 'the coding tools take a local path inside the project, not a drive path';
+const NOT_ISOLATED = 'sandbox mode is on and this sandbox is not isolated, so the coding tools are off';
+const BUDGET_SPENT = 'run wall-clock budget exhausted; no time remains for this call';
+export function guidance(error) {
+    return { error, guidance: true };
+}
+export function isError(value) {
+    return isRecord(value) && 'error' in value;
+}
+export function shellQuote(text) {
+    return `'${text.split("'").join("'\\''")}'`;
+}
+export function errorText(error) {
+    if (error instanceof Error) {
+        return error.name === 'AbortError' || error.name === 'AbortedError'
+            ? 'command aborted'
+            : error.message;
+    }
+    return String(error);
+}
+function workspaceRoot(ctx) {
+    const roots = ctx?.fsWriteRoots ?? [];
+    if (roots.length === 0) {
+        return guidance(NO_WORKSPACE);
+    }
+    if (roots.length > 1) {
+        return guidance(`the coding tools work in one writable directory, and the run grants ${roots.length}`);
+    }
+    const [root] = roots;
+    if (root.kind !== 'local' || path.dirname(root.root) === root.root) {
+        return guidance(DRIVE_WORKSPACE);
+    }
+    return root;
+}
+export async function workspaceKey(root, input) {
+    if (input.includes('://')) {
+        return { error: DRIVE_PATH };
+    }
+    const resolved = await resolveKey(path.resolve(root.root, input), [root], {
+        realpath: defaultRealpath
+    });
+    return 'error' in resolved ? resolved : resolved.key;
+}
+async function workspacePath(root, input) {
+    const key = await workspaceKey(root, input);
+    return isError(key) ? key : path.join(root.root, ...key.split('/').filter(Boolean));
+}
+export async function capped(text, stream, ctx) {
+    const output = createCapturedOutput(MAX_OUTPUT_CHARS, ctx?.spill?.sink(stream));
+    appendOutput(output, text);
+    return formatOutput(output, await output.sink?.close());
+}
+async function cappedResult({ stdout, stderr, exitCode }, ctx) {
+    return {
+        stdout: await capped(stdout, 'stdout', ctx),
+        stderr: await capped(stderr, 'stderr', ctx),
+        exitCode
+    };
+}
+function callTimeout(raw, ctx) {
+    if (raw !== undefined && !(typeof raw === 'number' && Number.isFinite(raw) && raw > 0)) {
+        return { error: 'timeoutMs must be a positive number' };
+    }
+    let timeout = Math.min(raw ?? SHELL_TIMEOUT_MS, MAX_TIMEOUT_MS);
+    if (ctx?.runBudget) {
+        const remaining = ctx.runBudget.deadlineMs - Date.now();
+        if (remaining <= 0) {
+            return guidance(BUDGET_SPENT);
+        }
+        timeout = Math.min(timeout, remaining);
+    }
+    return Math.floor(timeout);
+}
+export class CodingSession {
+    sandbox;
+    deniedRoots;
+    _bind;
+    _workspaces;
+    _runs;
+    constructor(sandbox, deniedRoots = []) {
+        this.sandbox = sandbox;
+        this.deniedRoots = deniedRoots;
+        this._bind = `__qvac_dir="\${TMPDIR:-/tmp}"/qvac-coding-${b4a.toHex(randomBytes(8))}`;
+        this._workspaces = new Map();
+        this._runs = new Map();
+    }
+    effect(ctx) {
+        return ctx?.planMode || !this.sandbox.isolated ? 'write' : 'read';
+    }
+    refusal(ctx) {
+        return ctx?.sandboxMode && !this.sandbox.isolated ? guidance(NOT_ISOLATED) : null;
+    }
+    async workspace(ctx) {
+        const root = this.refusal(ctx) ?? workspaceRoot(ctx);
+        if (isError(root)) {
+            return root;
+        }
+        const deny = await canonicalDenyRoots(this.deniedRoots, defaultRealpath);
+        return deny.some((each) => overlaps(root.root, each)) ? guidance(DENIED_WORKSPACE) : root;
+    }
+    policyVersion() {
+        return JSON.stringify({
+            sandbox: this.sandbox.name,
+            isolated: this.sandbox.isolated,
+            deniedRoots: [...this.deniedRoots].sort()
+        });
+    }
+    statePath(runId) {
+        return `${STATE_DIR}/${b4a.toHex(b4a.from(runId))}`;
+    }
+    open(root, runId) {
+        this._runs.set(runId, root.root);
+        let workspace = this._workspaces.get(root.root);
+        if (!workspace) {
+            workspace = this.sandbox.open(root.root);
+            workspace.catch(() => this._workspaces.delete(root.root));
+            this._workspaces.set(root.root, workspace);
+        }
+        return workspace;
+    }
+    workspaceOf(runId) {
+        const dir = this._runs.get(runId);
+        return dir === undefined ? null : (this._workspaces.get(dir) ?? null);
+    }
+    _prelude(runId) {
+        return [
+            this._bind,
+            `mkdir -p -m 700 ${STATE_DIR} ${STATE_DIR}/jobs`,
+            `__qvac_state=${this.statePath(runId)}`,
+            '[ -f "$__qvac_state.env" ] && . "$__qvac_state.env"',
+            '[ -f "$__qvac_state.cwd" ] && cd "$(cat "$__qvac_state.cwd")"'
+        ];
+    }
+    exec({ workspace, runId, line }, { timeoutMs, signal } = {}) {
+        const script = [
+            ...this._prelude(runId),
+            '__qvac_save() {',
+            '  __qvac_code=$?',
+            '  export -p > "$__qvac_state.tmp" && mv "$__qvac_state.tmp" "$__qvac_state.env"',
+            '  pwd > "$__qvac_state.cwd"',
+            '  exit $__qvac_code',
+            '}',
+            'trap __qvac_save EXIT',
+            `eval ${shellQuote(line)}`
+        ].join('\n');
+        return workspace.exec(script, { cwd: this._runs.get(runId), timeoutMs, signal });
+    }
+    jobLog(id) {
+        return `${STATE_DIR}/jobs/${id}.log`;
+    }
+    start({ workspace, runId, line }, id) {
+        const job = shellQuote(`trap wait EXIT\n${line}`);
+        const script = [...this._prelude(runId), `exec sh -c ${job} > ${this.jobLog(id)} 2>&1`];
+        return workspace.start(script.join('\n'), { cwd: this._runs.get(runId) });
+    }
+    execState(workspace, line) {
+        return workspace.exec(`${this._bind}\n${line}`);
+    }
+    async endRun(runId) {
+        const workspace = this.workspaceOf(runId);
+        this._runs.delete(runId);
+        if (workspace) {
+            const state = this.statePath(runId);
+            await this.execState(await workspace, `rm -f ${state}.env ${state}.cwd ${state}.tmp`);
+        }
+    }
+    async close() {
+        const workspaces = await Promise.allSettled(this._workspaces.values());
+        this._workspaces.clear();
+        this._runs.clear();
+        await Promise.allSettled(workspaces.map(async (each) => {
+            if (each.status !== 'fulfilled')
+                return;
+            try {
+                await this.execState(each.value, `rm -rf ${STATE_DIR}`);
+            }
+            finally {
+                await each.value.close();
+            }
+        }));
+    }
+}
+const SHELL_DESCRIPTION = 'Run a shell command in the project sandbox. The full sh line works: pipes, redirects, ' +
+    '&&, scripts and test runners. The working directory and exported variables carry over ' +
+    'to the next call in this run. The command has no stdin, so an interactive prompt waits ' +
+    'until the timeout: pass flags such as -y instead. Set background to start a dev server ' +
+    'or a watcher, then read it with shell_jobs.';
+const SHELL_PARAMETERS = {
+    type: 'object',
+    properties: {
+        command: { type: 'string', description: 'The sh command line' },
+        cwd: {
+            type: 'string',
+            description: 'Directory to run in, inside the project; it carries over'
+        },
+        timeoutMs: { type: 'number', description: 'default 300000, max 1800000' },
+        background: { type: 'boolean', description: 'Start it as a job and return its id at once' }
+    },
+    required: ['command']
+};
+async function shellLine(root, args) {
+    const command = String(args.command ?? '');
+    if (typeof args.cwd !== 'string' || !args.cwd) {
+        return command;
+    }
+    const cwd = await workspacePath(root, args.cwd);
+    return isError(cwd) ? cwd : `cd ${shellQuote(cwd)} && ${command}`;
+}
+async function runShell({ session, start }, args, ctx) {
+    const root = await session.workspace(ctx);
+    if (isError(root)) {
+        return root;
+    }
+    const line = await shellLine(root, args);
+    const timeoutMs = callTimeout(args.timeoutMs, ctx);
+    if (isError(line)) {
+        return line;
+    }
+    if (isError(timeoutMs)) {
+        return timeoutMs;
+    }
+    const runId = ctx?.runId ?? '';
+    try {
+        const call = { workspace: await session.open(root, runId), runId, line };
+        if (args.background === true) {
+            return await start(call);
+        }
+        return await cappedResult(await session.exec(call, { timeoutMs, signal: ctx?.signal }), ctx);
+    }
+    catch (error) {
+        return { error: errorText(error) };
+    }
+}
+export function shellTool(options) {
+    const { session } = options;
+    return {
+        name: 'shell',
+        toolset: 'coding',
+        policyVersion: session.policyVersion(),
+        description: SHELL_DESCRIPTION,
+        parameters: SHELL_PARAMETERS,
+        effect: (_args, ctx) => session.effect(ctx),
+        quote: (args) => (typeof args.command === 'string' ? args.command : null),
+        validate(args) {
+            return typeof args.command === 'string' && args.command.trim()
+                ? null
+                : 'command must be a non-empty string';
+        },
+        execute: (args, ctx) => runShell(options, args, ctx)
+    };
+}

package/dist-lib/plugins/coding/write-file.d.ts

@@ -0,0 +1,3 @@
+import type { ToolDefinition } from '../../lib/contract/index.ts';
+import { type CodingSession } from './session.ts';
+export declare function writeFileTool(session: CodingSession): ToolDefinition;

package/dist-lib/plugins/coding/write-file.js

@@ -0,0 +1,52 @@
+import { writeText } from '../../lib/tools/fs/write.js';
+import { errorText, isError, workspaceKey } from './session.js';
+async function fileKey(root, file) {
+    const key = await workspaceKey(root, file);
+    return key === '/' ? { error: 'path names the project folder, not a file' } : key;
+}
+async function writeFile(session, args, ctx) {
+    const root = await session.workspace(ctx);
+    if (isError(root)) {
+        return root;
+    }
+    const file = String(args.path);
+    const key = await fileKey(root, file);
+    if (isError(key)) {
+        return key;
+    }
+    try {
+        const existed = (await root.drive.entry(key)) !== null;
+        await writeText(root.drive, key, String(args.content));
+        return { path: file, written: existed ? 'overwritten' : 'created' };
+    }
+    catch (error) {
+        return { error: errorText(error) };
+    }
+}
+export function writeFileTool(session) {
+    return {
+        name: 'write_file',
+        toolset: 'coding',
+        policyVersion: session.policyVersion(),
+        description: 'Create a file or overwrite it with the full content, inside the project. Parent ' +
+            'directories are created as needed. A relative path starts at the project folder.',
+        parameters: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'File path' },
+                content: { type: 'string', description: 'Full file content' }
+            },
+            required: ['path', 'content']
+        },
+        effect: (_args, ctx) => session.effect(ctx),
+        quote: (args) => typeof args.path === 'string' && typeof args.content === 'string'
+            ? `write ${args.path}, ${args.content.length} chars`
+            : null,
+        validate(args) {
+            return typeof args.path === 'string' && args.path.trim() && typeof args.content === 'string'
+                ? null
+                : 'path must be a non-empty string and content a string';
+        },
+        execute: (args, ctx) => writeFile(session, args, ctx)
+    };
+}

package/dist-lib/plugins/command-hooks/index.d.ts

@@ -0,0 +1,88 @@
+import type { HarnessPlugin, PluginSetup } from '../../lib/plugins/index.ts';
+declare const EVENTS: {
+    readonly PreToolUse: 'preToolCall';
+    readonly PostToolUse: 'postToolCall';
+    readonly PostToolUseFailure: 'toolFailure';
+    readonly UserPromptSubmit: 'promptSubmit';
+    readonly Stop: 'stop';
+    readonly PreCompact: 'preFold';
+    readonly SubagentStart: 'preToolCall';
+    readonly SubagentStop: 'postToolCall';
+};
+declare const SKIPPED: readonly ['SessionStart', 'SessionEnd', 'Notification', 'PermissionRequest'];
+export type ClaudeHookEvent = keyof typeof EVENTS;
+export type SkippedClaudeHookEvent = (typeof SKIPPED)[number];
+export interface ClaudeHookCommand {
+    readonly type: 'command';
+    readonly command: string;
+    readonly timeout?: number | undefined;
+}
+export interface ClaudeHookMatcher {
+    readonly matcher?: string;
+    readonly hooks: readonly ClaudeHookCommand[];
+}
+export type ClaudeHooks = {
+    readonly [Event in ClaudeHookEvent | SkippedClaudeHookEvent]?: readonly ClaudeHookMatcher[];
+};
+interface Readable {
+    on(event: 'data', listener: (chunk: Uint8Array) => void): unknown;
+}
+interface Writable {
+    on(event: 'error', listener: (error: Error) => void): unknown;
+    write(chunk: string): unknown;
+    end(): unknown;
+}
+export interface CommandProcess {
+    readonly pid?: number | undefined;
+    readonly stdin: Writable | null;
+    readonly stdout: Readable | null;
+    readonly stderr: Readable | null;
+    on(event: 'close', listener: (code: number | null) => void): unknown;
+    on(event: 'error', listener: (error: Error) => void): unknown;
+}
+export interface SpawnOptions {
+    readonly cwd: string;
+    readonly env: Record<string, string>;
+}
+export type SpawnCommand = (command: string, options: SpawnOptions) => CommandProcess;
+export interface CommandHooksOptions {
+    readonly cwd?: string;
+    readonly spawn?: SpawnCommand;
+}
+export declare class CommandHooks implements HarnessPlugin {
+    static readonly EVENTS: {
+        readonly PreToolUse: 'preToolCall';
+        readonly PostToolUse: 'postToolCall';
+        readonly PostToolUseFailure: 'toolFailure';
+        readonly UserPromptSubmit: 'promptSubmit';
+        readonly Stop: 'stop';
+        readonly PreCompact: 'preFold';
+        readonly SubagentStart: 'preToolCall';
+        readonly SubagentStop: 'postToolCall';
+    };
+    static readonly spawn: SpawnCommand;
+    readonly name = "command-hooks";
+    readonly api = 1;
+    readonly addons: {
+        'bare-subprocess': () => Promise<{
+            constants: Record<string, number>;
+            errors: typeof import("bare-subprocess").errors;
+            Subprocess: typeof import("bare-subprocess").Subprocess;
+            spawn(file: string, args?: string[] | null, opts?: import("bare-subprocess").SpawnOptions): import("bare-subprocess").Subprocess;
+            spawn(file: string, opts?: import("bare-subprocess").SpawnOptions): import("bare-subprocess").Subprocess;
+            spawnSync(file: string, args?: string[] | null, opts?: import("bare-subprocess").SpawnSyncOptions): import("bare-subprocess").SpawnSyncResult;
+            spawnSync(file: string, opts?: import("bare-subprocess").SpawnSyncOptions): import("bare-subprocess").SpawnSyncResult;
+            default: typeof import("bare-subprocess");
+        }>;
+    };
+    private readonly _hooks;
+    private readonly _cwd;
+    private readonly _spawn;
+    private readonly _stops;
+    constructor(hooks: ClaudeHooks | undefined, options?: CommandHooksOptions);
+    validate(): string | null;
+    setup(): PluginSetup;
+    private _run;
+    private _stopState;
+}
+export {};