@guilz-dev/belay 0.1.0

package/dist/core/judge-config.js

@@ -0,0 +1,85 @@
+import { normalizeJudgeProvider } from './config.js';
+export const JUDGE_PROFILE_LOCAL_OLLAMA = {
+    provider: 'ollama',
+    model: 'gemma4:e2b',
+    endpoint: 'http://localhost:11434',
+    timeoutMs: 25000,
+    keepAlive: '30m',
+};
+export const JUDGE_PROFILES = {
+    'local-ollama': JUDGE_PROFILE_LOCAL_OLLAMA,
+};
+export function resolveJudgeConfig(input = {}) {
+    if (input.judgeProvider) {
+        const provider = normalizeJudgeProvider(input.judgeProvider);
+        const base = provider === 'openai-compatible' ? openAiCompatibleBase(input) : JUDGE_PROFILE_LOCAL_OLLAMA;
+        return {
+            ...base,
+            model: input.judgeModel ?? base.model,
+            endpoint: input.judgeEndpoint?.trim() || base.endpoint,
+        };
+    }
+    if (input.judgeProfile) {
+        const profile = JUDGE_PROFILES[input.judgeProfile];
+        return {
+            ...profile,
+            model: input.judgeModel ?? profile.model,
+            endpoint: input.judgeEndpoint?.trim() || profile.endpoint,
+        };
+    }
+    if (input.existingJudge) {
+        return { ...input.existingJudge };
+    }
+    return { ...JUDGE_PROFILE_LOCAL_OLLAMA };
+}
+function openAiCompatibleBase(input) {
+    return {
+        provider: 'openai-compatible',
+        model: input.judgeModel ?? 'auto',
+        timeoutMs: 8000,
+        endpoint: input.judgeEndpoint?.trim() ?? null,
+        keepAlive: null,
+    };
+}
+export class CloudJudgeConsentRequiredError extends Error {
+    constructor() {
+        super('Cloud judge sends redacted shell commands to an external endpoint and requires an API key in BELAY_JUDGE_API_KEY or OPENAI_API_KEY. ' +
+            'Pass --accept-cloud-judge to confirm, or use --judge-profile local-ollama for local-only Tier1.');
+        this.name = 'CloudJudgeConsentRequiredError';
+    }
+}
+export class JudgeEndpointRequiredError extends Error {
+    constructor() {
+        super('openai-compatible judge requires --judge-endpoint (or judge.endpoint in config). No default cloud base URL is applied.');
+        this.name = 'JudgeEndpointRequiredError';
+    }
+}
+function isCloudJudgeConfig(judge) {
+    return judge.provider === 'openai-compatible';
+}
+export function assertJudgeEndpoint(judge) {
+    if (judge.provider === 'openai-compatible' && !judge.endpoint?.trim()) {
+        throw new JudgeEndpointRequiredError();
+    }
+}
+export function resolveInitJudgeConfig(input) {
+    if (input.hasExplicitJudgeFlags) {
+        const judge = resolveJudgeConfig({
+            judgeProfile: input.judgeProfile,
+            judgeProvider: input.judgeProvider,
+            judgeModel: input.judgeModel,
+            judgeEndpoint: input.judgeEndpoint,
+        });
+        if (isCloudJudgeConfig(judge) && !input.acceptCloudJudge) {
+            throw new CloudJudgeConsentRequiredError();
+        }
+        assertJudgeEndpoint(judge);
+        return judge;
+    }
+    if (!input.isFresh && input.existingJudge) {
+        const judge = resolveJudgeConfig({ existingJudge: input.existingJudge });
+        assertJudgeEndpoint(judge);
+        return judge;
+    }
+    return resolveJudgeConfig({ judgeProfile: 'local-ollama' });
+}

package/dist/core/judge-doctor.d.ts

@@ -0,0 +1,7 @@
+import type { BelayConfigV4 } from './config.js';
+export interface JudgeDoctorResult {
+    issues: string[];
+    warnings: string[];
+    notes: string[];
+}
+export declare function diagnoseJudge(config: BelayConfigV4): Promise<JudgeDoctorResult>;

package/dist/core/judge-doctor.js

@@ -0,0 +1,124 @@
+import { normalizeJudgeProvider, scrubOptionsFromConfig } from './config.js';
+import { resolveJudgeApiKey } from './judge-api-key.js';
+import { assertJudgeEndpoint } from './judge-config.js';
+import { createOllamaJudge, createOpenAiCompatibleJudge } from './v2/judge.js';
+import { loadPinnedJudgeModels, resolveCloudModel } from './v2/judge-factory.js';
+export async function diagnoseJudge(config) {
+    const issues = [];
+    const warnings = [];
+    const notes = [];
+    const judge = config.judge;
+    const provider = normalizeJudgeProvider(judge.provider);
+    notes.push(`Judge provider: ${provider}`);
+    notes.push(`Judge model requested: ${judge.model}`);
+    if (config.policy.modelAssist.enabled) {
+        warnings.push('policy.modelAssist is enabled but is not wired to v2 Tier1. Use top-level judge instead.');
+    }
+    if (provider === 'openai-compatible') {
+        warnings.push('Cloud judge egress is enabled. Commands are redacted (R23) before send, but path structure and intent may still leave the repo.');
+        try {
+            assertJudgeEndpoint(judge);
+            notes.push(`OpenAI-compatible endpoint: ${judge.endpoint}`);
+        }
+        catch {
+            issues.push('openai-compatible judge requires judge.endpoint. No default cloud base URL is applied.');
+            return { issues, warnings, notes };
+        }
+        const keyInfo = resolveJudgeApiKey();
+        if (!keyInfo.key) {
+            issues.push('BELAY_JUDGE_API_KEY / OPENAI_API_KEY is not set. Tier1 cloud judge will fail closed to ask.');
+        }
+        else {
+            notes.push(`API key source: ${keyInfo.source}`);
+        }
+        const pinnedModels = await loadPinnedJudgeModels();
+        const resolved = resolveCloudModel(judge.model, pinnedModels['openai-compatible']);
+        notes.push(`Resolved model: ${resolved.resolved}`);
+        if (keyInfo.key && judge.endpoint?.trim()) {
+            const traced = createOpenAiCompatibleJudge({
+                endpoint: judge.endpoint.trim(),
+                modelRequested: judge.model,
+                modelResolved: resolved.resolved,
+                timeoutMs: Math.min(judge.timeoutMs, 5000),
+                apiKey: keyInfo.key,
+                sensitivePaths: config.classifier.sensitivePaths,
+                scrubOptions: scrubOptionsFromConfig(config),
+                fetchImpl: async () => new Response(JSON.stringify({
+                    choices: [
+                        {
+                            message: {
+                                content: JSON.stringify({
+                                    external_change: false,
+                                    destroys_outside_repo: false,
+                                    destroys_history_or_secrets: false,
+                                    reason: 'doctor_dry_run',
+                                }),
+                            },
+                        },
+                    ],
+                }), { status: 200 }),
+            });
+            const dryRun = await traced.evaluate({
+                text: 'git status',
+                context: { cwd: process.cwd(), repoRoot: process.cwd() },
+            });
+            if (dryRun.reason.startsWith('openai_compatible_') ||
+                dryRun.reason === 'outbound_scrub_failed') {
+                issues.push(`OpenAI-compatible judge dry-run failed: ${dryRun.reason}`);
+            }
+            else {
+                notes.push('OpenAI-compatible judge dry-run succeeded.');
+            }
+        }
+        return { issues, warnings, notes };
+    }
+    const endpoint = judge.endpoint ?? 'http://127.0.0.1:11434';
+    notes.push(`Ollama endpoint: ${endpoint}`);
+    try {
+        const response = await fetch(`${endpoint.replace(/\/$/, '')}/api/tags`, {
+            signal: AbortSignal.timeout(3000),
+        });
+        if (!response.ok) {
+            issues.push(`Ollama endpoint unreachable (HTTP ${response.status}). Tier1 will fail closed.`);
+        }
+        else {
+            const tags = (await response.json());
+            const names = (tags.models ?? []).map((entry) => entry.name ?? '');
+            const hasModel = names.some((name) => name === judge.model || name.startsWith(`${judge.model}:`));
+            if (!hasModel) {
+                issues.push(`Ollama model "${judge.model}" is not present. Pull it before enforce mode.`);
+            }
+            else {
+                notes.push(`Ollama model "${judge.model}" is available.`);
+            }
+        }
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : 'connection failed';
+        issues.push(`Ollama endpoint unreachable (${detail}). Tier1 will fail closed.`);
+    }
+    const warm = createOllamaJudge({
+        model: judge.model,
+        baseUrl: endpoint,
+        timeoutMs: Math.min(judge.timeoutMs, 5000),
+        fetchImpl: async () => new Response(JSON.stringify({
+            response: JSON.stringify({
+                external_change: false,
+                destroys_outside_repo: false,
+                destroys_history_or_secrets: false,
+                reason: 'doctor_warm',
+            }),
+        }), { status: 200 }),
+    });
+    const warmResult = await warm.evaluate({
+        text: 'git status',
+        context: { cwd: process.cwd(), repoRoot: process.cwd() },
+    });
+    if (warmResult.reason === 'ollama_unavailable' || warmResult.reason === 'ollama_parse_error') {
+        issues.push(`Ollama warm call failed: ${warmResult.reason}`);
+    }
+    else {
+        notes.push('Ollama warm call succeeded.');
+    }
+    return { issues, warnings, notes };
+}

package/dist/core/judgment.d.ts

@@ -0,0 +1,6 @@
+import type { Assessment, ConfidenceThresholds, HookVerdict } from './types.js';
+export declare function verdictFromConfidence(assessment: Assessment, thresholds: ConfidenceThresholds, unknownLocalEffect: 'allow_flagged' | 'deny'): HookVerdict;
+export declare function mergeAgentAssessment(independent: Assessment, agent?: Assessment): {
+    assessment: Assessment;
+    mismatch: boolean;
+};

package/dist/core/judgment.js

@@ -0,0 +1,38 @@
+export function verdictFromConfidence(assessment, thresholds, unknownLocalEffect) {
+    if (assessment.external || assessment.reversibility === 'irreversible') {
+        if (assessment.confidence >= thresholds.allow && !assessment.external) {
+            return 'allow_flagged';
+        }
+        return 'deny_pending_approval';
+    }
+    if (assessment.confidence >= thresholds.allow) {
+        return 'allow';
+    }
+    if (assessment.confidence >= thresholds.flag) {
+        return 'allow_flagged';
+    }
+    if (unknownLocalEffect === 'deny') {
+        return 'deny_pending_approval';
+    }
+    return 'allow_flagged';
+}
+export function mergeAgentAssessment(independent, agent) {
+    if (!agent) {
+        return { assessment: independent, mismatch: false };
+    }
+    const mismatch = (agent.external === false && independent.external === true) ||
+        (agent.reversibility === 'reversible' && independent.reversibility === 'irreversible');
+    const confidence = mismatch
+        ? Math.min(independent.confidence, 0.55)
+        : Math.min(0.99, independent.confidence + 0.05);
+    return {
+        assessment: {
+            ...independent,
+            confidence,
+            signals: mismatch
+                ? [...independent.signals, 'agent_assessment_mismatch']
+                : [...independent.signals, 'agent_assessment_agreement'],
+        },
+        mismatch,
+    };
+}

package/dist/core/notify.d.ts

@@ -0,0 +1,13 @@
+export interface DenyNotificationConfig {
+    webhookUrl?: string;
+    commandHook?: string;
+}
+export interface DenyNotificationEvent {
+    approvalId: string;
+    reason: string;
+    summary: string;
+    repoRoot: string;
+    fingerprint: string;
+    approvalToken?: string;
+}
+export declare function notifyDeny(config: DenyNotificationConfig, event: DenyNotificationEvent): Promise<void>;

package/dist/core/notify.js

@@ -0,0 +1,44 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+export async function notifyDeny(config, event) {
+    const payload = JSON.stringify(event);
+    if (config.webhookUrl) {
+        try {
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(), 5000);
+            try {
+                await fetch(config.webhookUrl, {
+                    method: 'POST',
+                    headers: { 'content-type': 'application/json' },
+                    body: payload,
+                    signal: controller.signal,
+                });
+            }
+            finally {
+                clearTimeout(timeout);
+            }
+        }
+        catch {
+            // best-effort notification
+        }
+    }
+    if (config.commandHook) {
+        try {
+            await execFileAsync(config.commandHook, [], {
+                env: {
+                    ...process.env,
+                    BELAY_APPROVAL_ID: event.approvalId,
+                    BELAY_REASON: event.reason,
+                    BELAY_SUMMARY: event.summary,
+                    BELAY_REPO_ROOT: event.repoRoot,
+                    BELAY_FINGERPRINT: event.fingerprint,
+                    BELAY_APPROVAL_TOKEN: event.approvalToken ?? '',
+                },
+            });
+        }
+        catch {
+            // best-effort notification
+        }
+    }
+}

package/dist/core/path-utils.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Resolve symlinks for the longest existing prefix of `targetPath`, then append
+ * any non-existent suffix without further resolution. Keeps path comparisons
+ * symmetric when one side is a not-yet-created file (e.g. transactional diff,
+ * fs-scope allowlist matching).
+ */
+export declare function canonicalPath(targetPath: string): string;
+export declare function pathWithinRoot(root: string, targetPath: string): boolean;
+export declare function relativeWithinRepo(repoRoot: string, targetPath: string): string | null;
+export declare function normalizeToken(token: string, repoRoot: string): string;
+export declare function resolveMutationTarget(token: string, cwd: string): string | null;
+export declare function hasOutsideRepoPath(tokens: string[], cwd: string, repoRoot: string): boolean;

package/dist/core/path-utils.js

@@ -0,0 +1,107 @@
+import { existsSync, realpathSync } from 'node:fs';
+import path from 'node:path';
+/**
+ * Resolve symlinks for the longest existing prefix of `targetPath`, then append
+ * any non-existent suffix without further resolution. Keeps path comparisons
+ * symmetric when one side is a not-yet-created file (e.g. transactional diff,
+ * fs-scope allowlist matching).
+ */
+export function canonicalPath(targetPath) {
+    const resolved = path.resolve(targetPath);
+    if (!resolved) {
+        return resolved;
+    }
+    const parsed = path.parse(resolved);
+    let current = parsed.root;
+    const relativeParts = path
+        .relative(parsed.root || '.', resolved)
+        .split(path.sep)
+        .filter(Boolean);
+    for (let i = 0; i < relativeParts.length; i++) {
+        const segment = relativeParts[i];
+        if (!segment) {
+            continue;
+        }
+        const candidate = current === '' ? segment : path.join(current, segment);
+        if (!existsSync(candidate)) {
+            return path.join(candidate, ...relativeParts.slice(i + 1));
+        }
+        try {
+            current = realpathSync.native(candidate);
+        }
+        catch {
+            return path.join(candidate, ...relativeParts.slice(i + 1));
+        }
+    }
+    return current;
+}
+export function pathWithinRoot(root, targetPath) {
+    const resolvedRoot = canonicalPath(root);
+    const resolvedTarget = canonicalPath(targetPath);
+    const relativePath = path.relative(resolvedRoot, resolvedTarget);
+    if (relativePath === '') {
+        return true;
+    }
+    return !relativePath.startsWith('..') && !path.isAbsolute(relativePath);
+}
+export function relativeWithinRepo(repoRoot, targetPath) {
+    const resolvedRoot = canonicalPath(repoRoot);
+    const resolvedTarget = canonicalPath(targetPath);
+    const relativePath = path.relative(resolvedRoot, resolvedTarget);
+    if (relativePath === '') {
+        return '.';
+    }
+    if (relativePath.startsWith('..')) {
+        return null;
+    }
+    return relativePath;
+}
+export function normalizeToken(token, repoRoot) {
+    if (!path.isAbsolute(token)) {
+        return token;
+    }
+    const relativePath = relativeWithinRepo(repoRoot, token);
+    return relativePath ?? token;
+}
+export function resolveMutationTarget(token, cwd) {
+    if (!token || token === '--' || token.startsWith('-')) {
+        return null;
+    }
+    if (token === '2>' || token === '1>' || token === '&>' || token === '1>>' || token === '2>>') {
+        return null;
+    }
+    if (path.isAbsolute(token)) {
+        return canonicalPath(token);
+    }
+    if (token.startsWith('./') || token.startsWith('../')) {
+        return canonicalPath(path.resolve(cwd, token));
+    }
+    if (!token.includes('/') && !token.includes('\\')) {
+        return canonicalPath(path.resolve(cwd, token));
+    }
+    return canonicalPath(path.resolve(cwd, token));
+}
+function looksLikePathToken(token) {
+    if (!token || token === '--' || token.startsWith('-')) {
+        return false;
+    }
+    if (path.isAbsolute(token)) {
+        return true;
+    }
+    if (token.startsWith('./') || token.startsWith('../')) {
+        return true;
+    }
+    return token.includes('/') || token.includes('\\');
+}
+export function hasOutsideRepoPath(tokens, cwd, repoRoot) {
+    return tokens.some((token) => {
+        if (!looksLikePathToken(token)) {
+            return false;
+        }
+        const resolved = resolveMutationTarget(token, cwd);
+        if (!resolved) {
+            return false;
+        }
+        return relativeWithinRepo(repoRoot, resolved) === null;
+    });
+}

package/dist/core/reclassify.d.ts

@@ -0,0 +1,15 @@
+import type { AuditRecord } from './audit-types.js';
+import type { BelayConfigV3 } from './config.js';
+import type { ClassifyResult } from './types.js';
+export interface ReclassifyDiff {
+    timestamp?: string;
+    event?: string;
+    summary?: string;
+    fingerprint?: string;
+    previousVerdict: string;
+    previousReason: string;
+    nextVerdict: string;
+    nextReason: string;
+}
+export declare function reclassifyAuditRecord(record: AuditRecord, config: BelayConfigV3, repoRoot: string): Promise<ClassifyResult | null>;
+export declare function diffReclassification(record: AuditRecord, config: BelayConfigV3, repoRoot: string): Promise<ReclassifyDiff | null>;

package/dist/core/reclassify.js

@@ -0,0 +1,82 @@
+import { getAdapter } from '../adapters/registry.js';
+import { repoShellClassifierOptions } from '../adapters/shared/gate-runtime.js';
+import { detectAdapterName } from '../config-io.js';
+import { GATE_EVENTS } from './audit-types.js';
+import { classifyGatedAction, normalizeGatedAction } from './gate-engine.js';
+function shellCommandFromSummary(summary) {
+    const trimmed = summary.trim();
+    return trimmed || null;
+}
+function classifierOptionsForRepo(config, repoRoot) {
+    const adapter = getAdapter(config.adapter ?? detectAdapterName(repoRoot));
+    return repoShellClassifierOptions(config, repoRoot, adapter.layout);
+}
+export async function reclassifyAuditRecord(record, config, repoRoot) {
+    if (!record.event || !GATE_EVENTS.has(record.event)) {
+        return null;
+    }
+    const kind = record.kind === 'tool' || record.kind === 'subagent' ? record.kind : 'shell';
+    const summary = record.summary ?? '';
+    try {
+        if (kind === 'shell') {
+            const command = shellCommandFromSummary(summary);
+            if (!command) {
+                return null;
+            }
+            const action = normalizeGatedAction({
+                kind: 'shell',
+                repoRoot,
+                cwd: repoRoot,
+                command,
+            });
+            return await classifyGatedAction(action, config, classifierOptionsForRepo(config, repoRoot));
+        }
+        if (kind === 'subagent') {
+            const action = normalizeGatedAction({
+                kind: 'subagent',
+                repoRoot,
+                cwd: repoRoot,
+                payload: {
+                    tool_name: 'Task',
+                    tool_input: { description: summary },
+                },
+            });
+            return await classifyGatedAction(action, config, classifierOptionsForRepo(config, repoRoot));
+        }
+        const action = normalizeGatedAction({
+            kind: 'tool',
+            repoRoot,
+            cwd: repoRoot,
+            toolName: 'Shell',
+            payload: {
+                tool_name: 'Shell',
+                tool_input: { command: summary },
+            },
+        });
+        return await classifyGatedAction(action, config, classifierOptionsForRepo(config, repoRoot));
+    }
+    catch {
+        return null;
+    }
+}
+export async function diffReclassification(record, config, repoRoot) {
+    const next = await reclassifyAuditRecord(record, config, repoRoot);
+    if (!next) {
+        return null;
+    }
+    const previousVerdict = record.verdict ?? 'unknown';
+    const previousReason = record.reason ?? 'unknown';
+    if (previousVerdict === next.verdict && previousReason === next.reason) {
+        return null;
+    }
+    return {
+        timestamp: record.timestamp,
+        event: record.event,
+        summary: record.summary,
+        fingerprint: record.fingerprint,
+        previousVerdict,
+        previousReason,
+        nextVerdict: next.verdict,
+        nextReason: next.reason,
+    };
+}

package/dist/core/recover-advice.d.ts

@@ -0,0 +1,30 @@
+import type { GitProbeResult } from './recover-git-probe.js';
+import type { Assessment } from './types.js';
+export interface RecoverTargetInput {
+    timestamp?: string;
+    fingerprint?: string;
+    summary: string;
+    reason: string;
+    effect?: string;
+    location?: string;
+    permission?: string;
+    assessment?: Assessment;
+}
+export interface RecoverAdviceInput {
+    repoRoot: string;
+    target: RecoverTargetInput;
+    git?: GitProbeResult;
+    /** Assessment confidence below this skips specific recovery commands (defaults to flag threshold). */
+    minAssessmentConfidence?: number;
+}
+export interface RecoverAdviceResult {
+    recoverable: boolean;
+    confidence: 'high' | 'medium';
+    disclaimer: string[];
+    advice: string[];
+    warnings: string[];
+}
+export declare const RECOVER_DISCLAIMER: string[];
+export declare const SHOW_DONT_RUN_LEAD = "These steps may help undo the observed effect \u2014 confirm each step before running:";
+export declare function containsDeniedRecoveryPattern(text: string): boolean;
+export declare function buildRecoverAdvice(input: RecoverAdviceInput): RecoverAdviceResult;