@guilz-dev/belay 0.3.0 → 0.4.0

package/dist/core/verdict/judge-session-broker.js

@@ -0,0 +1,195 @@
+import { buildJudgeSessionKey, evaluateSessionReuse, } from './judge-session-guard.js';
+import { MutexRegistry } from './judge-session-mutex.js';
+export class JudgeSessionBroker {
+    sessions = new Map();
+    mutexes = new MutexRegistry();
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    listSessions() {
+        return [...this.sessions.values()];
+    }
+    invalidateSession(sessionKey, reason) {
+        const session = this.sessions.get(sessionKey);
+        if (session) {
+            session.lastResetReason = reason;
+            session.state = 'idle';
+        }
+        this.sessions.delete(sessionKey);
+    }
+    stopAll(reason = 'manual_stop') {
+        const count = this.sessions.size;
+        for (const session of this.sessions.values()) {
+            session.lastResetReason = reason;
+            session.state = 'idle';
+        }
+        this.sessions.clear();
+        this.mutexes.clear();
+        return count;
+    }
+    async evaluate(request, timeoutMs) {
+        const sessionKey = buildJudgeSessionKey(request.keyParts);
+        return this.mutexes.forKey(sessionKey).run(() => this.evaluateExclusive(request, timeoutMs));
+    }
+    async evaluateExclusive(request, timeoutMs) {
+        const sessionKey = buildJudgeSessionKey(request.keyParts);
+        const providerId = request.keyParts.providerId;
+        const existing = this.sessions.get(sessionKey);
+        const reuseDecision = evaluateSessionReuse(existing?.keyParts ?? null, request.keyParts, existing?.budget ?? null, this.options.config, Date.now(), request.promptBytes);
+        const resetReason = reuseDecision.canReuse ? undefined : reuseDecision.resetReason;
+        let session = existing;
+        if (!reuseDecision.canReuse || !session) {
+            session = {
+                keyParts: request.keyParts,
+                budget: {
+                    turnCount: 0,
+                    createdAtMs: Date.now(),
+                    lastUsedAtMs: Date.now(),
+                    promptBytes: 0,
+                },
+                state: 'busy',
+                lastResetReason: resetReason ?? 'initial',
+            };
+            this.enforceProviderSessionCap(providerId, sessionKey);
+            this.sessions.set(sessionKey, session);
+        }
+        else {
+            session.state = 'busy';
+            session.budget.lastUsedAtMs = Date.now();
+        }
+        const invocation = reuseDecision.canReuse && session.providerResumeId
+            ? this.buildResumeInvocation(request.invocation, providerId, session.providerResumeId)
+            : request.invocation;
+        const resumed = reuseDecision.canReuse && Boolean(session.providerResumeId);
+        try {
+            const raw = await this.options.runCommand(invocation, timeoutMs);
+            session.budget.turnCount += 1;
+            session.budget.promptBytes += request.promptBytes;
+            session.budget.lastUsedAtMs = Date.now();
+            session.state = 'idle';
+            const extracted = this.options.extractResumeId?.(providerId, raw) ??
+                extractProviderResumeId(providerId, raw) ??
+                undefined;
+            if (extracted) {
+                session.providerResumeId = extracted;
+            }
+            return {
+                raw,
+                reused: resumed,
+                resetReason: session.lastResetReason,
+                providerResumeId: session.providerResumeId,
+            };
+        }
+        catch (error) {
+            session.state = 'idle';
+            session.lastResetReason = 'cli_error';
+            this.sessions.delete(sessionKey);
+            throw error;
+        }
+    }
+    enforceProviderSessionCap(providerId, keepKey) {
+        const cap = this.options.config.maxSessionsPerProvider;
+        const sameProvider = [...this.sessions.entries()].filter(([, record]) => record.keyParts.providerId === providerId);
+        if (sameProvider.length < cap) {
+            return;
+        }
+        for (const [key] of sameProvider) {
+            if (key === keepKey) {
+                continue;
+            }
+            this.sessions.delete(key);
+            if (this.sessions.size < cap) {
+                break;
+            }
+        }
+    }
+    buildResumeInvocation(base, providerId, resumeId) {
+        if (providerId === 'cursor') {
+            const args = [...base.args];
+            const modelIndex = args.indexOf('--model');
+            const model = modelIndex >= 0 ? args[modelIndex + 1] : undefined;
+            const prompt = args[args.length - 1];
+            return {
+                binary: base.binary,
+                args: [
+                    '--print',
+                    '--output-format',
+                    'json',
+                    '--mode',
+                    'ask',
+                    '--sandbox',
+                    'enabled',
+                    '--trust',
+                    '--resume',
+                    resumeId,
+                    ...(model ? ['--model', model] : []),
+                    prompt,
+                ],
+            };
+        }
+        if (providerId === 'claude') {
+            return {
+                ...base,
+                args: [...base.args, '--continue', resumeId],
+            };
+        }
+        return base;
+    }
+}
+export function extractProviderResumeId(providerId, raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        const candidates = [
+            parsed.chat_id,
+            parsed.chatId,
+            parsed.session_id,
+            parsed.sessionId,
+            parsed.result?.chat_id,
+            parsed.result?.session_id,
+        ];
+        for (const candidate of candidates) {
+            if (typeof candidate === 'string' && candidate.trim()) {
+                return candidate.trim();
+            }
+        }
+    }
+    catch {
+        // fall through
+    }
+    if (providerId === 'cursor') {
+        const match = raw.match(/"chat_id"\s*:\s*"([^"]+)"/);
+        if (match?.[1]) {
+            return match[1];
+        }
+    }
+    return null;
+}
+const repoBrokers = new Map();
+export function getRepoJudgeSessionBroker(repoRoot, options) {
+    const existing = repoBrokers.get(repoRoot);
+    if (existing) {
+        return existing;
+    }
+    const broker = new JudgeSessionBroker(options);
+    repoBrokers.set(repoRoot, broker);
+    return broker;
+}
+export function stopRepoJudgeSessionBroker(repoRoot, reason = 'manual_stop') {
+    const broker = repoBrokers.get(repoRoot);
+    if (!broker) {
+        return 0;
+    }
+    const count = broker.stopAll(reason);
+    repoBrokers.delete(repoRoot);
+    return count;
+}
+export function resetJudgeSessionBrokersForTests() {
+    for (const broker of repoBrokers.values()) {
+        broker.stopAll('manual_stop');
+    }
+    repoBrokers.clear();
+}
+export function listRepoJudgeSessionBrokers() {
+    return [...repoBrokers.keys()];
+}

package/dist/core/verdict/judge-session-guard.d.ts

@@ -0,0 +1,27 @@
+import type { JudgeProviderId } from './judge-catalog.js';
+import type { BelayJudgeSessionConfig } from './judge-runtime-config.js';
+export type JudgeSessionResetReason = 'provider_mismatch' | 'model_mismatch' | 'repo_mismatch' | 'mode_mismatch' | 'cli_version_mismatch' | 'max_turns_exceeded' | 'max_age_exceeded' | 'max_idle_exceeded' | 'max_prompt_bytes_exceeded' | 'parse_failure' | 'non_json_response' | 'cli_error' | 'timeout' | 'kill_switch' | 'manual_stop' | 'budget_exhausted' | 'session_disabled' | 'provider_not_allowlisted' | 'initial';
+export type JudgeFallbackReason = 'session_disabled' | 'provider_not_allowlisted' | 'session_unavailable' | 'guard_reset' | 'parse_error' | 'non_json_response' | 'cli_error' | 'timeout' | 'connect_timeout' | 'eval_timeout' | 'parse_timeout' | 'version_mismatch' | 'kill_switch' | 'shadow_forced_spawn' | 'unsafe_option_rejected' | 'broker_busy_reset' | `${Exclude<JudgeProviderId, 'ollama'>}_cli_spawn_error` | `${Exclude<JudgeProviderId, 'ollama'>}_cli_nonzero` | `${Exclude<JudgeProviderId, 'ollama'>}_cli_unavailable` | `${Exclude<JudgeProviderId, 'ollama'>}_cli_parse_error`;
+export interface JudgeSessionKeyParts {
+    providerId: JudgeProviderId;
+    model: string;
+    repoRoot: string;
+    judgeMode: string;
+    cliVersion: string;
+}
+export interface JudgeSessionBudget {
+    turnCount: number;
+    createdAtMs: number;
+    lastUsedAtMs: number;
+    promptBytes: number;
+}
+export interface JudgeSessionGuardDecision {
+    canReuse: boolean;
+    resetReason?: JudgeSessionResetReason;
+    sessionKey: string;
+}
+export declare function buildJudgeSessionKey(parts: JudgeSessionKeyParts): string;
+export declare function evaluateSessionReuse(existing: JudgeSessionKeyParts | null, requested: JudgeSessionKeyParts, budget: JudgeSessionBudget | null, config: BelayJudgeSessionConfig, now?: number, incomingPromptBytes?: number): JudgeSessionGuardDecision;
+export declare function exceedsPromptBudget(promptBytes: number, config: BelayJudgeSessionConfig, existingBudget?: JudgeSessionBudget | null): boolean;
+export declare function guardFailClosedFallbackReason(resetReason: JudgeSessionResetReason): JudgeFallbackReason;
+export declare function transportFallbackToFailClosedReason(providerId: Exclude<JudgeProviderId, 'ollama'>, fallback: JudgeFallbackReason | undefined): string;

package/dist/core/verdict/judge-session-guard.js

@@ -0,0 +1,91 @@
+export function buildJudgeSessionKey(parts) {
+    return [parts.providerId, parts.model, parts.repoRoot, parts.judgeMode, parts.cliVersion].join(':');
+}
+export function evaluateSessionReuse(existing, requested, budget, config, now = Date.now(), incomingPromptBytes = 0) {
+    const sessionKey = buildJudgeSessionKey(requested);
+    if (!config.enabled) {
+        return { canReuse: false, resetReason: 'session_disabled', sessionKey };
+    }
+    if (!config.providerAllowlist.includes(requested.providerId)) {
+        return { canReuse: false, resetReason: 'provider_not_allowlisted', sessionKey };
+    }
+    if (!existing || !budget) {
+        return { canReuse: false, resetReason: 'initial', sessionKey };
+    }
+    const existingKey = buildJudgeSessionKey(existing);
+    if (existingKey !== sessionKey) {
+        if (existing.providerId !== requested.providerId) {
+            return { canReuse: false, resetReason: 'provider_mismatch', sessionKey };
+        }
+        if (existing.model !== requested.model) {
+            return { canReuse: false, resetReason: 'model_mismatch', sessionKey };
+        }
+        if (existing.repoRoot !== requested.repoRoot) {
+            return { canReuse: false, resetReason: 'repo_mismatch', sessionKey };
+        }
+        if (existing.judgeMode !== requested.judgeMode) {
+            return { canReuse: false, resetReason: 'mode_mismatch', sessionKey };
+        }
+        if (existing.cliVersion !== requested.cliVersion) {
+            return { canReuse: false, resetReason: 'cli_version_mismatch', sessionKey };
+        }
+        return { canReuse: false, resetReason: 'provider_mismatch', sessionKey };
+    }
+    if (budget.turnCount >= config.maxTurns) {
+        return { canReuse: false, resetReason: 'max_turns_exceeded', sessionKey };
+    }
+    if (now - budget.createdAtMs >= config.maxAgeMs) {
+        return { canReuse: false, resetReason: 'max_age_exceeded', sessionKey };
+    }
+    if (now - budget.lastUsedAtMs >= config.maxIdleMs) {
+        return { canReuse: false, resetReason: 'max_idle_exceeded', sessionKey };
+    }
+    if (budget.promptBytes + incomingPromptBytes > config.maxPromptBytes) {
+        return { canReuse: false, resetReason: 'max_prompt_bytes_exceeded', sessionKey };
+    }
+    return { canReuse: true, sessionKey };
+}
+export function exceedsPromptBudget(promptBytes, config, existingBudget = null) {
+    const total = (existingBudget?.promptBytes ?? 0) + promptBytes;
+    return total > config.maxPromptBytes;
+}
+export function guardFailClosedFallbackReason(resetReason) {
+    switch (resetReason) {
+        case 'parse_failure':
+            return 'parse_error';
+        case 'non_json_response':
+            return 'non_json_response';
+        case 'cli_error':
+            return 'cli_error';
+        case 'timeout':
+            return 'timeout';
+        case 'cli_version_mismatch':
+            return 'version_mismatch';
+        case 'kill_switch':
+            return 'kill_switch';
+        case 'session_disabled':
+            return 'session_disabled';
+        case 'provider_not_allowlisted':
+            return 'provider_not_allowlisted';
+        case 'max_prompt_bytes_exceeded':
+            return 'guard_reset';
+        default:
+            return 'guard_reset';
+    }
+}
+export function transportFallbackToFailClosedReason(providerId, fallback) {
+    if (!fallback) {
+        return `${providerId}_cli_parse_error`;
+    }
+    if (fallback.endsWith('_cli_unavailable') || fallback.endsWith('_cli_parse_error')) {
+        return fallback;
+    }
+    switch (fallback) {
+        case 'non_json_response':
+        case 'parse_error':
+        case 'parse_timeout':
+            return `${providerId}_cli_parse_error`;
+        default:
+            return `${providerId}_cli_unavailable`;
+    }
+}

package/dist/core/verdict/judge-session-kill-switch.d.ts

@@ -0,0 +1,11 @@
+export declare const JUDGE_SESSION_KILL_FILE = "judge-session-kill.json";
+export interface JudgeSessionKillSwitchRecord {
+    triggered: boolean;
+    at: string;
+    reason?: string;
+}
+export declare function judgeSessionKillSwitchPath(stateDir: string): string;
+export declare function readJudgeSessionKillSwitch(stateDir: string): Promise<JudgeSessionKillSwitchRecord | null>;
+export declare function isJudgeSessionKillSwitchPersisted(stateDir: string): Promise<boolean>;
+export declare function persistJudgeSessionKillSwitch(stateDir: string, reason?: string): Promise<void>;
+export declare function clearJudgeSessionKillSwitch(stateDir: string): Promise<void>;

package/dist/core/verdict/judge-session-kill-switch.js

@@ -0,0 +1,43 @@
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, unlink, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+export const JUDGE_SESSION_KILL_FILE = 'judge-session-kill.json';
+export function judgeSessionKillSwitchPath(stateDir) {
+    return path.join(stateDir, JUDGE_SESSION_KILL_FILE);
+}
+export async function readJudgeSessionKillSwitch(stateDir) {
+    const filePath = judgeSessionKillSwitchPath(stateDir);
+    if (!existsSync(filePath)) {
+        return null;
+    }
+    try {
+        const raw = JSON.parse(await readFile(filePath, 'utf8'));
+        return raw.triggered === true ? raw : null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function isJudgeSessionKillSwitchPersisted(stateDir) {
+    const record = await readJudgeSessionKillSwitch(stateDir);
+    return record?.triggered === true;
+}
+export async function persistJudgeSessionKillSwitch(stateDir, reason = 'shadow_mismatch') {
+    await mkdir(stateDir, { recursive: true, mode: 0o700 });
+    const record = {
+        triggered: true,
+        at: new Date().toISOString(),
+        reason,
+    };
+    await writeFile(judgeSessionKillSwitchPath(stateDir), JSON.stringify(record), {
+        encoding: 'utf8',
+        mode: 0o600,
+    });
+}
+export async function clearJudgeSessionKillSwitch(stateDir) {
+    const filePath = judgeSessionKillSwitchPath(stateDir);
+    if (!existsSync(filePath)) {
+        return;
+    }
+    await unlink(filePath);
+}

package/dist/core/verdict/judge-session-mutex.d.ts

@@ -0,0 +1,9 @@
+export declare class AsyncMutex {
+    private chain;
+    run<T>(fn: () => Promise<T>): Promise<T>;
+}
+export declare class MutexRegistry {
+    private readonly mutexes;
+    forKey(key: string): AsyncMutex;
+    clear(): void;
+}

package/dist/core/verdict/judge-session-mutex.js

@@ -0,0 +1,23 @@
+export class AsyncMutex {
+    chain = Promise.resolve();
+    run(fn) {
+        const next = this.chain.then(fn);
+        this.chain = next.then(() => undefined, () => undefined);
+        return next;
+    }
+}
+export class MutexRegistry {
+    mutexes = new Map();
+    forKey(key) {
+        const existing = this.mutexes.get(key);
+        if (existing) {
+            return existing;
+        }
+        const created = new AsyncMutex();
+        this.mutexes.set(key, created);
+        return created;
+    }
+    clear() {
+        this.mutexes.clear();
+    }
+}

package/dist/core/verdict/judge-shadow.d.ts

@@ -0,0 +1,24 @@
+import type { BelayJudgeShadowConfig } from './judge-runtime-config.js';
+import type { Tier1Verdict } from './types.js';
+export interface JudgeShadowState {
+    compared: number;
+    mismatches: number;
+    dailyCount: number;
+    dailyKey: string;
+    killSwitchTriggered: boolean;
+    mismatchWindow: boolean[];
+}
+export declare function setJudgeShadowClockForTests(next: () => Date): void;
+export declare function setJudgeShadowRandomForTests(next: () => number): void;
+export declare function resetJudgeShadowState(repoRoot?: string): void;
+export declare function isJudgeSessionKillSwitchActive(repoRoot: string, stateDir?: string): Promise<boolean>;
+export declare function triggerJudgeSessionKillSwitch(repoRoot: string, stateDir?: string, reason?: string): Promise<void>;
+export declare function shouldRunShadowComparison(repoRoot: string, providerId: string, config: BelayJudgeShadowConfig): boolean;
+export declare function verdictsEquivalent(a: Tier1Verdict, b: Tier1Verdict): boolean;
+export declare function recordShadowComparison(repoRoot: string, config: BelayJudgeShadowConfig, mismatch: boolean): {
+    compared: boolean;
+    mismatch: boolean;
+    mismatchRateWindow: number;
+    killSwitchTriggered: boolean;
+};
+export declare function judgeShadowAuditFields(repoRoot: string): Record<string, unknown>;

package/dist/core/verdict/judge-shadow.js

@@ -0,0 +1,116 @@
+import { isJudgeSessionKillSwitchPersisted, persistJudgeSessionKillSwitch, } from './judge-session-kill-switch.js';
+const shadowStates = new Map();
+let clock = () => new Date();
+let random = Math.random;
+export function setJudgeShadowClockForTests(next) {
+    clock = next;
+}
+export function setJudgeShadowRandomForTests(next) {
+    random = next;
+}
+export function resetJudgeShadowState(repoRoot) {
+    if (repoRoot) {
+        shadowStates.delete(repoRoot);
+        return;
+    }
+    shadowStates.clear();
+}
+function dailyKeyFor(date) {
+    return date.toISOString().slice(0, 10);
+}
+function getShadowState(repoRoot) {
+    const existing = shadowStates.get(repoRoot);
+    if (existing) {
+        const key = dailyKeyFor(clock());
+        if (existing.dailyKey !== key) {
+            existing.dailyCount = 0;
+            existing.dailyKey = key;
+        }
+        return existing;
+    }
+    const created = {
+        compared: 0,
+        mismatches: 0,
+        dailyCount: 0,
+        dailyKey: dailyKeyFor(clock()),
+        killSwitchTriggered: false,
+        mismatchWindow: [],
+    };
+    shadowStates.set(repoRoot, created);
+    return created;
+}
+export async function isJudgeSessionKillSwitchActive(repoRoot, stateDir) {
+    if (getShadowState(repoRoot).killSwitchTriggered) {
+        return true;
+    }
+    if (stateDir) {
+        return isJudgeSessionKillSwitchPersisted(stateDir);
+    }
+    return false;
+}
+export async function triggerJudgeSessionKillSwitch(repoRoot, stateDir, reason = 'shadow_mismatch') {
+    getShadowState(repoRoot).killSwitchTriggered = true;
+    if (stateDir) {
+        await persistJudgeSessionKillSwitch(stateDir, reason);
+    }
+}
+export function shouldRunShadowComparison(repoRoot, providerId, config) {
+    if (!config.enabled) {
+        return false;
+    }
+    if (!config.providerAllowlist.includes(providerId)) {
+        return false;
+    }
+    const state = getShadowState(repoRoot);
+    if (state.killSwitchTriggered) {
+        return false;
+    }
+    if (state.dailyCount >= config.dailyRequestCap) {
+        return false;
+    }
+    const rate = Math.min(config.sampleRate, config.sampleRateMax);
+    return random() < rate;
+}
+export function verdictsEquivalent(a, b) {
+    return (a.local_recoverable === b.local_recoverable &&
+        a.destroys_history_or_secrets === b.destroys_history_or_secrets);
+}
+export function recordShadowComparison(repoRoot, config, mismatch) {
+    const state = getShadowState(repoRoot);
+    state.compared += 1;
+    state.dailyCount += 1;
+    if (mismatch) {
+        state.mismatches += 1;
+    }
+    state.mismatchWindow.push(mismatch);
+    if (state.mismatchWindow.length > config.windowSize) {
+        state.mismatchWindow.shift();
+    }
+    const windowComparisons = state.mismatchWindow.length;
+    const windowMismatches = state.mismatchWindow.filter(Boolean).length;
+    const mismatchRateWindow = windowComparisons === 0 ? 0 : windowMismatches / windowComparisons;
+    if (windowComparisons >= Math.min(10, config.windowSize) &&
+        mismatchRateWindow > config.mismatchRateThreshold) {
+        state.killSwitchTriggered = true;
+    }
+    return {
+        compared: true,
+        mismatch,
+        mismatchRateWindow,
+        killSwitchTriggered: state.killSwitchTriggered,
+    };
+}
+export function judgeShadowAuditFields(repoRoot) {
+    const state = shadowStates.get(repoRoot);
+    if (!state) {
+        return {};
+    }
+    const windowComparisons = state.mismatchWindow.length;
+    const windowMismatches = state.mismatchWindow.filter(Boolean).length;
+    return {
+        judgeShadowCompared: state.compared > 0,
+        judgeShadowMismatch: state.mismatches > 0,
+        judgeShadowMismatchRateWindow: windowComparisons === 0 ? 0 : windowMismatches / windowComparisons,
+        judgeKillSwitchTriggered: state.killSwitchTriggered,
+    };
+}

package/dist/core/verdict/judge-transport.d.ts

@@ -0,0 +1,40 @@
+import type { JudgeProviderId } from './judge-catalog.js';
+import { type CliInvocation, type CliJudgeRunCommand } from './judge-cli.js';
+import type { BelayJudgeRuntimeConfig } from './judge-runtime-config.js';
+import { type JudgeFallbackReason, type JudgeSessionResetReason } from './judge-session-guard.js';
+import type { Tier1Verdict } from './types.js';
+export interface JudgeTransportContext {
+    providerId: Exclude<JudgeProviderId, 'ollama'>;
+    model: string;
+    repoRoot: string;
+    stateDir: string;
+    judgeMode: string;
+    runtime: BelayJudgeRuntimeConfig;
+    judgeTimeoutMs: number;
+}
+export interface JudgeTransportEvaluateRequest {
+    prompt: string;
+    context: JudgeTransportContext;
+}
+export interface JudgeTransportEvaluateResult {
+    raw: string;
+    verdict: Tier1Verdict | null;
+    transport: 'spawn' | 'session';
+    sessionUsed: boolean;
+    sessionReused: boolean;
+    fallbackReason?: JudgeFallbackReason;
+    sessionResetReason?: JudgeSessionResetReason;
+    shadowCompared?: boolean;
+    shadowMismatch?: boolean;
+    shadowMismatchRateWindow?: number;
+    killSwitchTriggered?: boolean;
+    sessionRefHash?: string;
+    connectMs: number;
+    evalMs: number;
+    parseMs: number;
+}
+export interface JudgeTransportBridgeOptions {
+    runCommand?: CliJudgeRunCommand;
+}
+export declare function evaluateWithJudgeTransport(request: JudgeTransportEvaluateRequest, options?: JudgeTransportBridgeOptions): Promise<JudgeTransportEvaluateResult>;
+export declare function buildTransportInvocation(providerId: Exclude<JudgeProviderId, 'ollama'>, prompt: string, model: string): CliInvocation;