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

package/dist-lib/plugins/command-hooks/index.js

@@ -0,0 +1,338 @@
+import b4a from 'b4a';
+import { spawn } from 'child_process';
+import process from 'process';
+import { errorMessage, isRecord } from '../../lib/guards.js';
+import { execEnv } from '../../lib/helpers/spawn-path.js';
+import { hlog } from '../../lib/log.js';
+import { PluginRegistry } from '../../lib/plugins/index.js';
+const DEFAULT_TIMEOUT_S = 60;
+const STDERR_TAIL = 2_000;
+const SUBAGENT_MATCHER = 'delegate';
+const EVENTS = {
+    PreToolUse: 'preToolCall',
+    PostToolUse: 'postToolCall',
+    PostToolUseFailure: 'toolFailure',
+    UserPromptSubmit: 'promptSubmit',
+    Stop: 'stop',
+    PreCompact: 'preFold',
+    SubagentStart: 'preToolCall',
+    SubagentStop: 'postToolCall'
+};
+const SKIPPED = ['SessionStart', 'SessionEnd', 'Notification', 'PermissionRequest'];
+function isEvent(key) {
+    return Object.hasOwn(EVENTS, key);
+}
+function isSkipped(key) {
+    return SKIPPED.some((event) => event === key);
+}
+function wildcard(matcher) {
+    return !matcher || matcher === '*';
+}
+function toolEvent(event) {
+    return event === 'PreToolUse' || event === 'PostToolUse' || event === 'PostToolUseFailure';
+}
+function regexError(matcher) {
+    try {
+        new RegExp(`^(?:${matcher})$`);
+        return null;
+    }
+    catch (err) {
+        return errorMessage(err);
+    }
+}
+function commandError(event, hook) {
+    if (!isRecord(hook) || hook.type !== 'command') {
+        return `${event}: only type "command" is supported`;
+    }
+    if (typeof hook.command !== 'string' || !hook.command.trim()) {
+        return `${event}: a command is empty`;
+    }
+    const { timeout } = hook;
+    if (timeout !== undefined && !(typeof timeout === 'number' && timeout > 0)) {
+        return `${event}: a timeout must be above 0`;
+    }
+    return null;
+}
+function entryError(event, entry) {
+    if (!isRecord(entry) || !Array.isArray(entry.hooks)) {
+        return `${event}: each entry needs a hooks list`;
+    }
+    const { matcher } = entry;
+    if (event.startsWith('Subagent') && typeof matcher === 'string' && !wildcard(matcher)) {
+        return `${event}: matcher '${matcher}' names an agent type, and a delegate call has none`;
+    }
+    const invalid = toolEvent(event) && typeof matcher === 'string' && !wildcard(matcher);
+    const error = invalid ? regexError(matcher) : null;
+    if (error) {
+        return `${event}: matcher '${matcher}' is not a valid regex: ${error}`;
+    }
+    for (const hook of entry.hooks) {
+        const error = commandError(event, hook);
+        if (error) {
+            return error;
+        }
+    }
+    return null;
+}
+function outcomeMessage(outcome) {
+    if (outcome.kind === 'success')
+        return undefined;
+    return outcome.kind === 'error' || outcome.kind === 'guidance' ? outcome.message : outcome.reason;
+}
+function stdinOf(ctx, base, active) {
+    switch (ctx.phase) {
+        case 'preToolCall':
+            return { ...base, tool_name: ctx.toolName, tool_input: ctx.args, tool_use_id: ctx.callId };
+        case 'postToolCall':
+        case 'toolFailure':
+            return {
+                ...base,
+                tool_name: ctx.toolName,
+                tool_input: ctx.args,
+                tool_use_id: ctx.callId,
+                tool_response: ctx.result,
+                error: ctx.phase === 'toolFailure' ? outcomeMessage(ctx.outcome) : undefined
+            };
+        case 'promptSubmit':
+            return { ...base, prompt: ctx.text };
+        case 'stop':
+            return { ...base, stop_hook_active: active };
+        case 'preFold':
+            return { ...base, trigger: 'auto', custom_instructions: '' };
+        default:
+            return base;
+    }
+}
+function text(value) {
+    return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+function blocked(event, reason) {
+    const said = reason ?? `${event} hook blocked this`;
+    switch (event) {
+        case 'PreToolUse':
+        case 'SubagentStart':
+        case 'UserPromptSubmit':
+            return { kind: 'hook-rejection', error: said, guidance: true };
+        case 'PostToolUse':
+        case 'PostToolUseFailure':
+        case 'SubagentStop':
+            return { context: said };
+        case 'Stop':
+            return { continue: said };
+        case 'PreCompact':
+            hlog('PreCompact hook exited 2; a fold cannot be blocked', { reason: said });
+            return undefined;
+    }
+}
+function parsed(stdout) {
+    const trimmed = stdout.trim();
+    if (!trimmed.startsWith('{')) {
+        return null;
+    }
+    try {
+        const value = JSON.parse(trimmed);
+        return isRecord(value) ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+function permissionOf(value) {
+    return value === 'allow' || value === 'deny' || value === 'ask' ? value : undefined;
+}
+function fromJson(event, json) {
+    if (json.decision === 'block' && event !== 'PreCompact') {
+        return blocked(event, text(json.reason));
+    }
+    const specific = isRecord(json.hookSpecificOutput) ? json.hookSpecificOutput : {};
+    const extra = text(specific.additionalContext);
+    if (event === 'PreToolUse' || event === 'SubagentStart') {
+        const args = specific.updatedInput;
+        return {
+            args: isRecord(args) && !Array.isArray(args) ? args : undefined,
+            permission: permissionOf(specific.permissionDecision),
+            reason: text(specific.permissionDecisionReason) ?? text(json.reason)
+        };
+    }
+    if (event === 'Stop' || extra === undefined) {
+        return undefined;
+    }
+    return event === 'PreCompact' ? { instructions: extra } : { context: extra };
+}
+function answered(event, exit) {
+    const json = exit.code === 0 ? parsed(exit.stdout) : null;
+    if (json?.continue === false) {
+        return { halt: text(json.stopReason) ?? `${event} hook stopped the run` };
+    }
+    if (exit.code === 2) {
+        return blocked(event, text(exit.stderr));
+    }
+    if (exit.code !== 0) {
+        const tail = text(exit.stderr);
+        throw new Error(`command exited ${exit.code ?? 'on a signal'}${tail ? `: ${tail}` : ''}`);
+    }
+    if (json) {
+        return fromJson(event, json);
+    }
+    const plain = text(exit.stdout);
+    if (event === 'UserPromptSubmit' && plain !== undefined) {
+        return { context: plain };
+    }
+    return event === 'PreCompact' && plain !== undefined ? { instructions: plain } : undefined;
+}
+const spawnCommand = (command, { cwd, env }) => spawn('/bin/sh', ['-c', command], { cwd, env, detached: true, stdio: ['pipe', 'pipe', 'pipe'] });
+function abortedError(signal) {
+    const reason = signal?.reason;
+    return reason instanceof Error ? reason : new Error('command aborted');
+}
+function killOnAbort(child, signals, fail) {
+    const listening = signals.flatMap((signal) => signal ? [{ signal, listener: () => abort(signal) }] : []);
+    const detach = () => {
+        for (const { signal, listener } of listening) {
+            signal.removeEventListener('abort', listener);
+        }
+    };
+    const abort = (signal) => {
+        detach();
+        try {
+            if (child.pid) {
+                process.kill(-child.pid, 'SIGKILL');
+            }
+        }
+        catch {
+        }
+        fail(abortedError(signal));
+    };
+    for (const { signal, listener } of listening) {
+        if (signal.aborted) {
+            abort(signal);
+            break;
+        }
+        signal.addEventListener('abort', listener);
+    }
+    return detach;
+}
+function run(child, input, signals) {
+    const stdout = [];
+    const stderr = [];
+    child.stdout?.on('data', (chunk) => stdout.push(chunk));
+    child.stderr?.on('data', (chunk) => stderr.push(chunk));
+    child.stdin?.on('error', () => { });
+    child.stdin?.write(JSON.stringify(input));
+    child.stdin?.end();
+    return new Promise((resolve, reject) => {
+        const detach = killOnAbort(child, signals, reject);
+        child.on('error', (error) => {
+            detach();
+            reject(error);
+        });
+        child.on('close', (code) => {
+            detach();
+            resolve({
+                code,
+                stdout: b4a.toString(b4a.concat(stdout), 'utf8'),
+                stderr: b4a.toString(b4a.concat(stderr), 'utf8').slice(-STDERR_TAIL)
+            });
+        });
+    });
+}
+function commandsOf(event, entries) {
+    return entries
+        .flatMap(({ matcher, hooks }) => hooks.map(({ command, timeout }) => ({ matcher, command, timeout })))
+        .map((hook, i) => ({ ...hook, event, name: `${event}:${i + 1}` }))
+        .filter(({ matcher }) => event !== 'PreCompact' || wildcard(matcher) || matcher === 'auto');
+}
+function matcherOf(event, matcher) {
+    if (event === 'SubagentStart' || event === 'SubagentStop') {
+        return SUBAGENT_MATCHER;
+    }
+    return toolEvent(event) ? matcher : undefined;
+}
+export class CommandHooks {
+    static EVENTS = EVENTS;
+    static spawn = spawnCommand;
+    name = 'command-hooks';
+    api = PluginRegistry.API_VERSION;
+    addons = { 'bare-subprocess': () => import('bare-subprocess') };
+    _hooks;
+    _cwd;
+    _spawn;
+    _stops = new Map();
+    constructor(hooks, options = {}) {
+        this._hooks = hooks;
+        this._cwd = options.cwd ?? process.cwd();
+        this._spawn = options.spawn ?? spawnCommand;
+    }
+    validate() {
+        const config = this._hooks;
+        if (!isRecord(config)) {
+            return 'config must be the hooks object of a settings.json';
+        }
+        for (const [event, entries] of Object.entries(config)) {
+            if (isSkipped(event)) {
+                continue;
+            }
+            if (!isEvent(event)) {
+                return `unknown event '${event}'; supported: ${Object.keys(EVENTS).join(', ')}`;
+            }
+            if (!Array.isArray(entries)) {
+                return `${event} must be a list of matcher entries`;
+            }
+            for (const entry of entries) {
+                const error = entryError(event, entry);
+                if (error) {
+                    return error;
+                }
+            }
+        }
+        return null;
+    }
+    setup() {
+        const config = this._hooks;
+        const skipped = Object.keys(config).filter(isSkipped);
+        if (skipped.length) {
+            hlog('command-hooks: these events have no harness phase and never run', { events: skipped });
+        }
+        const commands = Object.entries(config).flatMap(([event, entries = []]) => isEvent(event) ? commandsOf(event, entries) : []);
+        const hooks = commands.map((spec) => ({
+            name: spec.name,
+            phase: EVENTS[spec.event],
+            matcher: matcherOf(spec.event, spec.matcher),
+            timeoutMs: (spec.timeout ?? DEFAULT_TIMEOUT_S) * 1000,
+            run: (ctx, options) => this._run(spec, ctx, options?.signal)
+        }));
+        if (commands.some(({ event }) => event === 'Stop')) {
+            hooks.push({
+                name: 'Stop:end',
+                phase: 'runEnd',
+                run: (ctx) => void this._stops.delete(ctx.runId)
+            });
+        }
+        return { hooks, teardown: () => this._stops.clear() };
+    }
+    async _run(spec, ctx, signal) {
+        if (ctx.phase === 'postToolCall' && ctx.outcome?.kind !== 'success') {
+            return undefined;
+        }
+        const stop = ctx.phase === 'stop' ? this._stopState(ctx.runId, ctx.round) : null;
+        const env = { ...execEnv(process.env, process.platform), CLAUDE_PROJECT_DIR: this._cwd };
+        const base = { hook_event_name: spec.event, session_id: ctx.runId, cwd: this._cwd };
+        const input = stdinOf(ctx, base, stop?.active ?? false);
+        const signals = [signal, ctx.phase === 'preToolCall' ? ctx.signal : undefined];
+        const exit = await run(this._spawn(spec.command, { cwd: this._cwd, env }), input, signals);
+        const result = answered(spec.event, exit);
+        if (stop) {
+            stop.continued ||= isRecord(result) && 'continue' in result;
+        }
+        return result;
+    }
+    _stopState(runId, round) {
+        const prior = this._stops.get(runId);
+        if (prior?.round === round) {
+            return prior;
+        }
+        const state = { round, active: prior?.continued ?? false, continued: false };
+        this._stops.set(runId, state);
+        return state;
+    }
+}

package/dist-lib/plugins/external-agents/acp.d.ts

@@ -0,0 +1,27 @@
+import type { TargetResult, TargetTask } from '../../lib/agent/index.ts';
+export declare const ACP_PROTOCOL_VERSION = 1;
+type Handler = (params: Record<string, unknown>) => unknown;
+export declare class AcpClient {
+    private readonly _send;
+    private readonly _pending;
+    private readonly _requests;
+    private readonly _notifications;
+    private _next;
+    private _closed;
+    constructor(send: (line: string) => void);
+    request(method: string, params: unknown): Promise<unknown>;
+    notify(method: string, params: unknown): void;
+    handle(method: string, handler: Handler): void;
+    on(method: string, handler: Handler): void;
+    receive(line: string): void;
+    close(error: Error): void;
+    private _answer;
+    private _reply;
+}
+export interface AcpTurnOptions {
+    signal: AbortSignal;
+    maxCostUsd?: number | undefined;
+    graceMs: number;
+}
+export declare function acpTurn(client: AcpClient, task: TargetTask, options: AcpTurnOptions): Promise<TargetResult>;
+export {};

package/dist-lib/plugins/external-agents/acp.js

@@ -0,0 +1,264 @@
+import { isRecord } from '../../lib/guards.js';
+export const ACP_PROTOCOL_VERSION = 1;
+const READ_KINDS = new Set(['read', 'search', 'think']);
+const READ_ONLY_MODE = 'read-only';
+export class AcpClient {
+    _send;
+    _pending = new Map();
+    _requests = new Map();
+    _notifications = new Map();
+    _next = 0;
+    _closed = null;
+    constructor(send) {
+        this._send = send;
+    }
+    request(method, params) {
+        if (this._closed) {
+            return Promise.reject(this._closed);
+        }
+        const id = this._next++;
+        return new Promise((resolve, reject) => {
+            this._pending.set(id, { resolve, reject });
+            this._send(JSON.stringify({ jsonrpc: '2.0', id, method, params }));
+        });
+    }
+    notify(method, params) {
+        if (!this._closed) {
+            this._send(JSON.stringify({ jsonrpc: '2.0', method, params }));
+        }
+    }
+    handle(method, handler) {
+        this._requests.set(method, handler);
+    }
+    on(method, handler) {
+        this._notifications.set(method, handler);
+    }
+    receive(line) {
+        const message = parse(line);
+        if (!message) {
+            return;
+        }
+        const params = isRecord(message.params) ? message.params : {};
+        if (typeof message.method === 'string') {
+            if ('id' in message) {
+                this._answer(message.id, message.method, params);
+            }
+            else {
+                this._notifications.get(message.method)?.(params);
+            }
+            return;
+        }
+        const id = Number(message.id);
+        const pending = this._pending.get(id);
+        if (!pending) {
+            return;
+        }
+        this._pending.delete(id);
+        if (isRecord(message.error)) {
+            pending.reject(new Error(String(message.error.message ?? 'the agent answered an error')));
+        }
+        else {
+            pending.resolve(message.result);
+        }
+    }
+    close(error) {
+        this._closed ??= error;
+        for (const pending of this._pending.values()) {
+            pending.reject(error);
+        }
+        this._pending.clear();
+    }
+    _answer(id, method, params) {
+        const handler = this._requests.get(method);
+        if (!handler) {
+            this._reply(id, { error: { code: -32601, message: `${method} is not supported` } });
+            return;
+        }
+        void Promise.resolve(handler(params)).then((result) => this._reply(id, { result }), (error) => this._reply(id, { error: { code: -32603, message: String(error) } }));
+    }
+    _reply(id, body) {
+        if (!this._closed) {
+            this._send(JSON.stringify({ jsonrpc: '2.0', id, ...body }));
+        }
+    }
+}
+function parse(line) {
+    try {
+        const message = JSON.parse(line);
+        return isRecord(message) ? message : null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function acpTurn(client, task, options) {
+    const { signal } = options;
+    const turn = {
+        task,
+        transcript: [],
+        kinds: new Map(),
+        text: '',
+        costUsd: undefined,
+        stop: null,
+        cancel: () => client.close(new Error('aborted'))
+    };
+    client.handle('session/request_permission', (params) => permission(turn, params, signal));
+    client.on('session/update', (params) => update(turn, params, options));
+    const onAbort = () => turn.cancel();
+    if (signal.aborted) {
+        onAbort();
+    }
+    else {
+        signal.addEventListener('abort', onAbort, { once: true });
+    }
+    try {
+        const stopReason = await prompt(client, turn, options);
+        turn.transcript.push({ type: 'end', stopReason });
+        return result(turn, stopReason, signal);
+    }
+    catch (error) {
+        turn.transcript.push({ type: 'error', message: String(Reflect.get(Object(error), 'message')) });
+        return {
+            status: signal.aborted ? 'aborted' : 'error',
+            text: turn.text || String(Reflect.get(Object(error), 'message')),
+            transcript: turn.transcript
+        };
+    }
+    finally {
+        signal.removeEventListener('abort', onAbort);
+    }
+}
+async function prompt(client, turn, { graceMs, signal }) {
+    await client.request('initialize', {
+        protocolVersion: ACP_PROTOCOL_VERSION,
+        clientCapabilities: { fs: { readTextFile: false, writeTextFile: false }, terminal: false }
+    });
+    const session = Object(await client.request('session/new', { cwd: turn.task.workdir, mcpServers: [] }));
+    const sessionId = String(session.sessionId);
+    const modes = Array.isArray(Object(session.modes).availableModes)
+        ? Object(session.modes).availableModes
+        : [];
+    if (turn.task.access === 'read' && modes.some((mode) => Object(mode).id === READ_ONLY_MODE)) {
+        await client.request('session/set_mode', { sessionId, modeId: READ_ONLY_MODE });
+    }
+    const asked = client.request('session/prompt', {
+        sessionId,
+        prompt: [{ type: 'text', text: turn.task.prompt }]
+    });
+    let gaveUp = () => { };
+    let grace;
+    const givenUp = new Promise((resolve) => {
+        gaveUp = () => resolve('cancelled');
+    });
+    turn.cancel = () => {
+        client.notify('session/cancel', { sessionId });
+        grace ??= setTimeout(gaveUp, graceMs);
+    };
+    if (signal.aborted) {
+        turn.cancel();
+    }
+    try {
+        const answered = await Promise.race([asked, givenUp]);
+        return typeof answered === 'string' ? answered : String(Object(answered).stopReason);
+    }
+    finally {
+        clearTimeout(grace);
+    }
+}
+function result(turn, stopReason, signal) {
+    const usage = turn.costUsd === undefined ? undefined : { costUsd: turn.costUsd };
+    const status = () => {
+        if (turn.stop === 'budget' ||
+            stopReason === 'max_tokens' ||
+            stopReason === 'max_turn_requests') {
+            return 'budget';
+        }
+        if (turn.stop === 'denied') {
+            return 'denied';
+        }
+        if (signal.aborted || stopReason === 'cancelled') {
+            return 'aborted';
+        }
+        return stopReason === 'refusal' ? 'denied' : 'answered';
+    };
+    return { status: status(), text: turn.text, usage, transcript: turn.transcript };
+}
+function permission(turn, params, signal) {
+    const call = Object(params.toolCall);
+    const id = String(call.toolCallId ?? '');
+    const kind = stricter(call.kind, turn.kinds.get(id));
+    const options = Array.isArray(params.options) ? params.options : [];
+    const allow = allowed(turn.task.access, kind);
+    const option = options.find((each) => Object(each).kind === (allow ? 'allow_once' : 'reject_once'));
+    const answer = signal.aborted || turn.stop || !option ? 'cancelled' : String(Object(option).optionId);
+    turn.transcript.push({ type: 'permission', id, title: call.title, kind, answer });
+    return answer === 'cancelled'
+        ? { outcome: { outcome: 'cancelled' } }
+        : { outcome: { outcome: 'selected', optionId: answer } };
+}
+function stricter(...kinds) {
+    const declared = kinds.filter((kind) => typeof kind === 'string').map(String);
+    return declared.find((kind) => !READ_KINDS.has(kind)) ?? declared[0] ?? 'other';
+}
+function allowed(access, kind) {
+    return access === 'write' || READ_KINDS.has(kind);
+}
+function halt(turn, why) {
+    if (!turn.stop) {
+        turn.stop = why;
+        turn.cancel();
+    }
+}
+function update(turn, params, options) {
+    const body = Object(params.update);
+    const kind = String(body.sessionUpdate);
+    if (kind === 'agent_message_chunk' || kind === 'agent_thought_chunk') {
+        const text = String(Object(body.content).text ?? '');
+        const type = kind === 'agent_message_chunk' ? 'message' : 'thought';
+        if (type === 'message') {
+            turn.text += text;
+        }
+        const last = turn.transcript.at(-1);
+        if (last?.type === type) {
+            last.text = `${String(last.text)}${text}`;
+        }
+        else {
+            turn.transcript.push({ type, text });
+        }
+    }
+    else if (kind === 'tool_call' || kind === 'tool_call_update') {
+        tool(turn, body);
+    }
+    else if (kind === 'usage_update') {
+        usage(turn, body, options);
+    }
+}
+function tool(turn, body) {
+    const id = String(body.toolCallId ?? '');
+    if (typeof body.kind === 'string') {
+        turn.kinds.set(id, body.kind);
+    }
+    const locations = Array.isArray(body.locations) ? body.locations : [];
+    const kind = turn.kinds.get(id);
+    turn.transcript.push({
+        type: 'tool',
+        id,
+        title: body.title,
+        kind,
+        status: body.status,
+        paths: locations.map((location) => Object(location).path)
+    });
+    if (turn.stop !== 'denied' && !allowed(turn.task.access, kind ?? 'other')) {
+        turn.transcript.push({ type: 'permission', id, title: body.title, kind, answer: 'denied' });
+        halt(turn, 'denied');
+    }
+}
+function usage(turn, body, { maxCostUsd }) {
+    const cost = Object(body.cost);
+    const costUsd = typeof cost.amount === 'number' ? cost.amount : undefined;
+    turn.costUsd = costUsd ?? turn.costUsd;
+    turn.transcript.push({ type: 'usage', used: body.used, size: body.size, costUsd });
+    if (maxCostUsd !== undefined && costUsd !== undefined && costUsd >= maxCostUsd) {
+        halt(turn, 'budget');
+    }
+}

package/dist-lib/plugins/external-agents/cli.d.ts

@@ -0,0 +1,3 @@
+import { type Protocol } from './targets.ts';
+export declare const claudeCli: Protocol;
+export declare const codexCli: Protocol;