@guilz-dev/belay 0.3.0 → 0.6.0

package/dist/core/verdict/containment.d.ts

@@ -6,13 +6,13 @@ export interface PathTargetAnalysis {
     signals: string[];
 }
 export declare function resolveTrustedPath(token: string, trustedCwd: string, trusted: boolean): string | null;
-export declare function locationForPath(resolvedPath: string | null, repoRoot: string): VerdictLocation;
+export declare function locationForPath(resolvedPath: string | null, repoRoot: string, trustedWorkspaceRoots?: string[]): VerdictLocation;
 export declare function isGitPath(resolvedPath: string, repoRoot: string): boolean;
-export declare function isHighStakesPath(resolvedPath: string, repoRoot: string, sensitivePaths: string[], protectedRoots?: string[]): boolean;
+export declare function isHighStakesPath(resolvedPath: string, repoRoot: string, sensitivePaths: string[], protectedRoots?: string[], trustedWorkspaceRoots?: string[]): boolean;
 /** ADR-002 M3: destructive shell head on git/sensitive path (not broad category ask). */
 export declare function isDestructiveMutationHead(head: string): boolean;
 export declare function touchesProtectedRoot(resolvedPath: string, protectedRoots: string[]): boolean;
-export declare function isDestructiveHighStakesMutation(head: string, resolvedPath: string, repoRoot: string, sensitivePaths: string[], protectedRoots?: string[]): boolean;
+export declare function isDestructiveHighStakesMutation(head: string, resolvedPath: string, repoRoot: string, sensitivePaths: string[], protectedRoots?: string[], trustedWorkspaceRoots?: string[]): boolean;
 export declare function analyzePathTargets(params: {
     targets: string[];
     cwd: string;
@@ -20,5 +20,6 @@ export declare function analyzePathTargets(params: {
     trustedCwd: boolean;
     sensitivePaths: string[];
     protectedArtifactRoots?: string[];
+    trustedWorkspaceRoots?: string[];
 }): PathTargetAnalysis;
 export declare function cwdRelative(repoRoot: string, cwd: string): string;

package/dist/core/verdict/containment.js

@@ -1,6 +1,6 @@
 import path from 'node:path';
 import { matchesSensitivePath } from '../glob.js';
-import { canonicalPath, pathWithinRoot, relativeWithinRepo, resolveMutationTarget, } from '../path-utils.js';
+import { canonicalPath, pathWithinRoot, relativeWithinRepo, resolveMutationTarget, resolveWorkspaceRootMatch, } from '../path-utils.js';
 import { isOutsideRepoSecretCredentialPath } from './persistent-paths.js';
 export { isOutsideRepoSecretCredentialPath, isPersistentAgentPath } from './persistent-paths.js';
 function expandHome(token) {
@@ -26,11 +26,11 @@ export function resolveTrustedPath(token, trustedCwd, trusted) {
     }
     return canonicalPath(path.resolve(trustedCwd, expanded));
 }
-export function locationForPath(resolvedPath, repoRoot) {
+export function locationForPath(resolvedPath, repoRoot, trustedWorkspaceRoots = []) {
     if (!resolvedPath) {
         return 'unknown';
     }
-    if (pathWithinRoot(repoRoot, resolvedPath)) {
+    if (resolveWorkspaceRootMatch(repoRoot, trustedWorkspaceRoots, resolvedPath)) {
         return 'repo_local';
     }
     return 'repo_outside';
@@ -41,17 +41,22 @@ export function isGitPath(resolvedPath, repoRoot) {
         return false;
     }
     const normalized = relative.replaceAll('\\', '/');
-    return normalized === '.git' || normalized.startsWith('.git/');
+    return (normalized === '.git' ||
+        normalized.startsWith('.git/') ||
+        normalized.endsWith('/.git') ||
+        normalized.includes('/.git/'));
 }
-export function isHighStakesPath(resolvedPath, repoRoot, sensitivePaths, protectedRoots = []) {
+export function isHighStakesPath(resolvedPath, repoRoot, sensitivePaths, protectedRoots = [], trustedWorkspaceRoots = []) {
     if (isGitPath(resolvedPath, repoRoot)) {
         return true;
     }
-    const relative = relativeWithinRepo(repoRoot, resolvedPath);
-    if (relative !== null && matchesSensitivePath(relative.replaceAll('\\', '/'), sensitivePaths)) {
+    const workspaceMatch = resolveWorkspaceRootMatch(repoRoot, trustedWorkspaceRoots, resolvedPath);
+    if (workspaceMatch !== null &&
+        matchesSensitivePath(workspaceMatch.relativePath.replaceAll('\\', '/'), sensitivePaths)) {
         return true;
     }
-    if (relative === null && isOutsideRepoSecretCredentialPath(resolvedPath)) {
+    if ((workspaceMatch === null || workspaceMatch.kind === 'trusted') &&
+        isOutsideRepoSecretCredentialPath(resolvedPath)) {
         return true;
     }
     return protectedRoots.some((root) => pathWithinRoot(root, resolvedPath));
@@ -73,14 +78,14 @@ export function isDestructiveMutationHead(head) {
 export function touchesProtectedRoot(resolvedPath, protectedRoots) {
     return protectedRoots.some((root) => pathWithinRoot(root, resolvedPath) || root === resolvedPath);
 }
-export function isDestructiveHighStakesMutation(head, resolvedPath, repoRoot, sensitivePaths, protectedRoots = []) {
+export function isDestructiveHighStakesMutation(head, resolvedPath, repoRoot, sensitivePaths, protectedRoots = [], trustedWorkspaceRoots = []) {
     if (touchesProtectedRoot(resolvedPath, protectedRoots)) {
         return true;
     }
     if (!isDestructiveMutationHead(head)) {
         return false;
     }
-    return isHighStakesPath(resolvedPath, repoRoot, sensitivePaths, []);
+    return isHighStakesPath(resolvedPath, repoRoot, sensitivePaths, [], trustedWorkspaceRoots);
 }
 export function analyzePathTargets(params) {
     const signals = [];
@@ -96,10 +101,10 @@ export function analyzePathTargets(params) {
     for (const target of params.targets) {
         const resolved = resolveTrustedPath(target, params.cwd, params.trustedCwd) ??
             resolveMutationTarget(target, params.cwd);
-        const location = locationForPath(resolved, params.repoRoot);
+        const location = locationForPath(resolved, params.repoRoot, params.trustedWorkspaceRoots);
         locations.add(location);
         if (resolved &&
-            isHighStakesPath(resolved, params.repoRoot, params.sensitivePaths, params.protectedArtifactRoots)) {
+            isHighStakesPath(resolved, params.repoRoot, params.sensitivePaths, params.protectedArtifactRoots, params.trustedWorkspaceRoots)) {
             isHighStakes = true;
             signals.push('high_stakes_path');
         }

package/dist/core/verdict/cursor-acp-client.d.ts

@@ -0,0 +1,67 @@
+import { type ChildProcessWithoutNullStreams, type SpawnOptionsWithoutStdio } from 'node:child_process';
+import type { CliJudgeRunCommand } from './judge-cli.js';
+interface AcpSessionResponse {
+    sessionId: string;
+    models?: {
+        currentModelId?: string;
+        availableModels?: Array<{
+            modelId?: string;
+        }>;
+    };
+    configOptions?: Array<{
+        id?: string;
+        currentValue?: string;
+        options?: Array<{
+            value?: string;
+        }>;
+    }>;
+}
+export type CursorAcpSpawn = (binary: string, args: string[], options: SpawnOptionsWithoutStdio & {
+    stdio: ['pipe', 'pipe', 'pipe'];
+}) => ChildProcessWithoutNullStreams;
+export type CursorAcpErrorKind = 'connect_timeout' | 'eval_timeout' | 'process_exit' | 'protocol_error';
+export declare class CursorAcpError extends Error {
+    readonly kind: CursorAcpErrorKind;
+    constructor(kind: CursorAcpErrorKind, message: string);
+}
+export interface CursorAcpJudgeRunnerOptions {
+    cwd: string;
+    connectTimeoutMs: number;
+    binary?: string;
+    spawnProcess?: CursorAcpSpawn;
+}
+export declare function resolveCursorAcpModelId(requested: string, session: AcpSessionResponse): string;
+export declare class CursorAcpJudgeRunner {
+    private readonly options;
+    private readonly binary;
+    private readonly spawnProcess;
+    private child;
+    private startPromise;
+    private connected;
+    private nextId;
+    private stdoutBuffer;
+    private stderrTail;
+    private readonly pending;
+    private readonly messageBuffers;
+    private activeSessionId;
+    constructor(options: CursorAcpJudgeRunnerOptions);
+    get sessionId(): string | null;
+    readonly run: CliJudgeRunCommand;
+    private evaluate;
+    stop(): Promise<void>;
+    private ensureConnected;
+    private start;
+    private createSession;
+    private request;
+    private notify;
+    private handleStdout;
+    private handleMessage;
+    private respond;
+    private respondError;
+    private handleProcessExit;
+    private rejectPending;
+    private withStderr;
+    private terminateChild;
+    private signalAndWait;
+}
+export {};

package/dist/core/verdict/cursor-acp-client.js

@@ -0,0 +1,345 @@
+import { spawn, } from 'node:child_process';
+export class CursorAcpError extends Error {
+    kind;
+    constructor(kind, message) {
+        super(message);
+        this.kind = kind;
+        this.name = 'CursorAcpError';
+    }
+}
+const STDERR_TAIL_LIMIT = 2_048;
+const TERMINATE_GRACE_MS = 250;
+function invocationValue(invocation, flag) {
+    const index = invocation.args.indexOf(flag);
+    return index >= 0 ? invocation.args[index + 1] : undefined;
+}
+function promptFromInvocation(invocation) {
+    if (invocation.stdin !== undefined) {
+        return invocation.stdin;
+    }
+    return invocation.args[invocation.args.length - 1] ?? '';
+}
+function modelIdsFromSession(session) {
+    const fromModels = session.models?.availableModels
+        ?.map((entry) => entry.modelId)
+        .filter((value) => Boolean(value));
+    if (fromModels?.length) {
+        return fromModels;
+    }
+    const modelOption = session.configOptions?.find((option) => option.id === 'model');
+    return (modelOption?.options
+        ?.map((entry) => entry.value)
+        .filter((value) => Boolean(value)) ?? []);
+}
+export function resolveCursorAcpModelId(requested, session) {
+    const available = modelIdsFromSession(session);
+    if (available.includes(requested)) {
+        return requested;
+    }
+    const parameterized = available.find((modelId) => modelId.startsWith(`${requested}[`));
+    return parameterized ?? requested;
+}
+export class CursorAcpJudgeRunner {
+    options;
+    binary;
+    spawnProcess;
+    child = null;
+    startPromise = null;
+    connected = false;
+    nextId = 0;
+    stdoutBuffer = '';
+    stderrTail = '';
+    pending = new Map();
+    messageBuffers = new Map();
+    activeSessionId = null;
+    constructor(options) {
+        this.options = options;
+        this.binary = options.binary ?? 'cursor-agent';
+        this.spawnProcess = options.spawnProcess ?? spawn;
+    }
+    get sessionId() {
+        return this.activeSessionId;
+    }
+    run = async (invocation, timeoutMs) => {
+        if (invocation.binary !== this.binary && invocation.binary !== 'cursor-agent') {
+            throw new CursorAcpError('protocol_error', `Cursor ACP runner cannot execute ${invocation.binary}`);
+        }
+        let totalTimer = null;
+        try {
+            const evaluation = this.evaluate(invocation, timeoutMs);
+            const totalTimeout = new Promise((_resolve, reject) => {
+                totalTimer = setTimeout(() => {
+                    reject(new CursorAcpError('eval_timeout', 'Cursor ACP evaluation timed out'));
+                }, timeoutMs);
+            });
+            return await Promise.race([evaluation, totalTimeout]);
+        }
+        catch (error) {
+            if (error instanceof CursorAcpError && error.kind === 'eval_timeout') {
+                this.notify('session/cancel', { sessionId: this.activeSessionId });
+            }
+            await this.stop();
+            throw error;
+        }
+        finally {
+            if (totalTimer) {
+                clearTimeout(totalTimer);
+            }
+        }
+    };
+    async evaluate(invocation, timeoutMs) {
+        await this.ensureConnected();
+        const requestedResumeId = invocationValue(invocation, '--resume');
+        const model = invocationValue(invocation, '--model') ?? 'composer-2.5';
+        const canReuse = Boolean(requestedResumeId) && requestedResumeId === this.activeSessionId;
+        if (!canReuse) {
+            await this.createSession(model);
+        }
+        const sessionId = this.activeSessionId;
+        if (!sessionId) {
+            throw new CursorAcpError('protocol_error', 'Cursor ACP session was not created');
+        }
+        this.messageBuffers.set(sessionId, '');
+        try {
+            await this.request('session/prompt', {
+                sessionId,
+                prompt: [{ type: 'text', text: promptFromInvocation(invocation) }],
+            }, timeoutMs, 'eval_timeout');
+            const raw = this.messageBuffers.get(sessionId)?.trim() ?? '';
+            if (!raw) {
+                throw new CursorAcpError('protocol_error', 'Cursor ACP returned no agent message');
+            }
+            return raw;
+        }
+        finally {
+            this.messageBuffers.delete(sessionId);
+        }
+    }
+    async stop() {
+        const child = this.child;
+        this.child = null;
+        this.connected = false;
+        this.startPromise = null;
+        this.activeSessionId = null;
+        this.stdoutBuffer = '';
+        this.messageBuffers.clear();
+        this.rejectPending(new CursorAcpError('process_exit', this.withStderr('Cursor ACP process stopped')));
+        if (child && child.exitCode === null) {
+            await this.terminateChild(child);
+        }
+    }
+    async ensureConnected() {
+        if (this.connected && this.child) {
+            return;
+        }
+        if (!this.startPromise) {
+            this.startPromise = this.start().finally(() => {
+                this.startPromise = null;
+            });
+        }
+        await this.startPromise;
+    }
+    async start() {
+        this.stderrTail = '';
+        const child = this.spawnProcess(this.binary, ['acp'], {
+            cwd: this.options.cwd,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        this.child = child;
+        child.stdout.on('data', (chunk) => this.handleStdout(String(chunk)));
+        child.stderr.on('data', (chunk) => {
+            this.stderrTail = `${this.stderrTail}${String(chunk)}`.slice(-STDERR_TAIL_LIMIT);
+        });
+        child.once('error', (error) => {
+            this.handleProcessExit(new CursorAcpError('process_exit', this.withStderr(error.message)), child);
+        });
+        child.once('close', (code) => {
+            this.handleProcessExit(new CursorAcpError('process_exit', this.withStderr(`Cursor ACP exited with code ${code ?? 'unknown'}`)), child);
+        });
+        try {
+            await this.request('initialize', {
+                protocolVersion: 1,
+                clientCapabilities: {
+                    fs: { readTextFile: false, writeTextFile: false },
+                    terminal: false,
+                },
+                clientInfo: {
+                    name: 'belay-judge',
+                    title: 'Belay Judge',
+                    version: '1',
+                },
+            }, this.options.connectTimeoutMs, 'connect_timeout');
+            await this.request('authenticate', { methodId: 'cursor_login' }, this.options.connectTimeoutMs, 'connect_timeout');
+            this.connected = true;
+        }
+        catch (error) {
+            await this.stop();
+            throw error;
+        }
+    }
+    async createSession(model) {
+        const previous = this.activeSessionId;
+        this.activeSessionId = null;
+        if (previous) {
+            await this.request('session/close', { sessionId: previous }, Math.min(this.options.connectTimeoutMs, 1_000), 'connect_timeout').catch(() => undefined);
+        }
+        const session = (await this.request('session/new', { cwd: this.options.cwd, mcpServers: [] }, this.options.connectTimeoutMs, 'connect_timeout'));
+        if (!session?.sessionId) {
+            throw new CursorAcpError('protocol_error', 'Cursor ACP session/new omitted sessionId');
+        }
+        this.activeSessionId = session.sessionId;
+        await this.request('session/set_config_option', { sessionId: session.sessionId, configId: 'mode', value: 'ask' }, this.options.connectTimeoutMs, 'connect_timeout');
+        await this.request('session/set_config_option', {
+            sessionId: session.sessionId,
+            configId: 'model',
+            value: resolveCursorAcpModelId(model, session),
+        }, this.options.connectTimeoutMs, 'connect_timeout');
+    }
+    request(method, params, timeoutMs, timeoutKind) {
+        const child = this.child;
+        if (!child?.stdin.writable) {
+            return Promise.reject(new CursorAcpError('process_exit', this.withStderr('Cursor ACP stdin is unavailable')));
+        }
+        const id = ++this.nextId;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new CursorAcpError(timeoutKind, `Cursor ACP ${method} timed out`));
+            }, timeoutMs);
+            this.pending.set(id, { method, resolve, reject, timer });
+            child.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', id, method, params })}\n`);
+        });
+    }
+    notify(method, params) {
+        if (!this.child?.stdin.writable) {
+            return;
+        }
+        this.child.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', method, params })}\n`);
+    }
+    handleStdout(chunk) {
+        this.stdoutBuffer += chunk;
+        const lines = this.stdoutBuffer.split('\n');
+        this.stdoutBuffer = lines.pop() ?? '';
+        for (const line of lines) {
+            if (!line.trim()) {
+                continue;
+            }
+            try {
+                this.handleMessage(JSON.parse(line));
+            }
+            catch {
+                const child = this.child;
+                this.handleProcessExit(new CursorAcpError('protocol_error', 'Cursor ACP emitted invalid JSON-RPC'), child);
+                if (child?.exitCode === null) {
+                    void this.terminateChild(child);
+                }
+            }
+        }
+    }
+    handleMessage(message) {
+        if (message.id !== undefined && !message.method) {
+            const pending = this.pending.get(message.id);
+            if (!pending) {
+                return;
+            }
+            clearTimeout(pending.timer);
+            this.pending.delete(message.id);
+            if (message.error !== undefined) {
+                pending.reject(new CursorAcpError('protocol_error', `Cursor ACP ${pending.method} failed: ${JSON.stringify(message.error)}`));
+            }
+            else {
+                pending.resolve(message.result);
+            }
+            return;
+        }
+        if (message.method === 'session/update') {
+            const sessionId = message.params?.sessionId;
+            const update = message.params?.update;
+            if (typeof sessionId !== 'string' || !update || typeof update !== 'object') {
+                return;
+            }
+            const record = update;
+            const content = record.content;
+            if (record.sessionUpdate === 'agent_message_chunk' &&
+                content &&
+                typeof content === 'object' &&
+                typeof content.text === 'string') {
+                const text = content.text;
+                this.messageBuffers.set(sessionId, `${this.messageBuffers.get(sessionId) ?? ''}${text}`);
+            }
+            return;
+        }
+        if (message.id !== undefined && message.method === 'session/request_permission') {
+            this.respond(message.id, { outcome: { outcome: 'cancelled' } });
+            return;
+        }
+        if (message.id !== undefined && message.method) {
+            this.respondError(message.id, -32601, 'Belay Judge does not expose client tools');
+        }
+    }
+    respond(id, result) {
+        this.child?.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', id, result })}\n`);
+    }
+    respondError(id, code, message) {
+        this.child?.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', id, error: { code, message } })}\n`);
+    }
+    handleProcessExit(error, exitedChild = this.child) {
+        if (exitedChild && this.child !== exitedChild) {
+            return;
+        }
+        this.child = null;
+        this.connected = false;
+        this.activeSessionId = null;
+        this.messageBuffers.clear();
+        this.rejectPending(error);
+    }
+    rejectPending(error) {
+        for (const pending of this.pending.values()) {
+            clearTimeout(pending.timer);
+            pending.reject(error);
+        }
+        this.pending.clear();
+    }
+    withStderr(message) {
+        const stderr = this.stderrTail.trim();
+        return stderr ? `${message}: ${stderr}` : message;
+    }
+    async terminateChild(child) {
+        if (child.exitCode !== null) {
+            return;
+        }
+        if (await this.signalAndWait(child, 'SIGTERM')) {
+            return;
+        }
+        await this.signalAndWait(child, 'SIGKILL');
+    }
+    signalAndWait(child, signal) {
+        if (child.exitCode !== null) {
+            return Promise.resolve(true);
+        }
+        return new Promise((resolve) => {
+            let settled = false;
+            const finish = (exited) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                child.off('close', onExit);
+                child.off('error', onExit);
+                resolve(exited);
+            };
+            const onExit = () => finish(true);
+            const timer = setTimeout(() => finish(child.exitCode !== null), TERMINATE_GRACE_MS);
+            child.once('close', onExit);
+            child.once('error', onExit);
+            try {
+                if (!child.kill(signal)) {
+                    finish(child.exitCode !== null);
+                }
+            }
+            catch {
+                finish(child.exitCode !== null);
+            }
+        });
+    }
+}

package/dist/core/verdict/egress-classify.d.ts

@@ -1,6 +1,6 @@
 /**
- * Tier0 egress tool classification (SPEC v2.1.3 R33–R34).
- * destructive → Tier0 ask | read → Tier0 allow | ambiguous → Tier1 (fail-closed)
+ * Egress tool classification (SPEC v2.1.3 R33–R34).
+ * destructive → ask | read → allow at egress layer | ambiguous → require_approval via PolicyEngine
  */
 export type EgressClassification = 'destructive' | 'read' | 'ambiguous';
 export declare function isEgressToolHead(head: string): boolean;

package/dist/core/verdict/egress-classify.js

@@ -1,6 +1,6 @@
 /**
- * Tier0 egress tool classification (SPEC v2.1.3 R33–R34).
- * destructive → Tier0 ask | read → Tier0 allow | ambiguous → Tier1 (fail-closed)
+ * Egress tool classification (SPEC v2.1.3 R33–R34).
+ * destructive → ask | read → allow at egress layer | ambiguous → require_approval via PolicyEngine
  */
 const EGRESS_TOOL_HEADS = new Set([
     'aws',

package/dist/core/verdict/git-classifier.d.ts

@@ -0,0 +1,26 @@
+import type { VerdictEffect } from './types.js';
+export interface NormalizedGitInvocation {
+    subcommand: string;
+    args: string[];
+    effectiveCwd?: string;
+    gitDir?: string;
+    workTree?: string;
+}
+export interface GitCommandSemantics {
+    effect: VerdictEffect;
+    pathTargets: string[];
+    scopeTargets: string[];
+    signals: string[];
+    egressClass?: 'read' | 'destructive' | 'ambiguous';
+    requiresAsk?: {
+        reason: string;
+        signals: string[];
+    };
+    effectiveCwd?: string;
+    gitWorkTree?: string;
+    normalizedKey: string;
+    isReadOnly: boolean;
+}
+export declare function normalizeGitInvocation(tokens: string[], baseCwd: string): NormalizedGitInvocation | null;
+export declare function isGitReadOnlyInvocation(tokens: string[], baseCwd: string): boolean;
+export declare function classifyGitCommand(tokens: string[], baseCwd: string): GitCommandSemantics | null;