govyn 0.0.1 → 0.2.5

package/dist/loop-detector.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Loop detection for the Govyn proxy server.
+ *
+ * Detects agents making repeated identical requests (same endpoint + same body hash)
+ * within a configurable time window. When the threshold is exceeded, the agent is
+ * flagged as looping and can be blocked via BudgetEnforcer.blockAgent().
+ *
+ * Sliding window implementation: per-agent, per-request-key array of timestamps.
+ * On each recordRequest, prune timestamps outside the window, then check count >= threshold.
+ */
+import type { AgentConfig, LoopDetectionConfig } from './types.js';
+/**
+ * LoopDetector tracks repeated identical requests per agent.
+ *
+ * Each "identical request" is identified by the combination of:
+ * - The upstream endpoint path
+ * - A hash of the request body (first 16 hex chars of SHA-256)
+ *
+ * When the same agent hits the same endpoint+bodyHash N times within M seconds,
+ * isLooping() returns true. Thresholds are configurable per agent.
+ */
+export declare class LoopDetector {
+    private defaultConfig;
+    private agentConfigs;
+    /** Map of agentId -> array of request windows (one per unique endpoint+bodyHash) */
+    private windows;
+    constructor(defaultConfig: LoopDetectionConfig, agentConfigs: Map<string, AgentConfig>);
+    /**
+     * Compute a compact hash of the request body for identity comparison.
+     *
+     * Uses SHA-256 truncated to 16 hex chars (64-bit) — sufficient for loop detection
+     * (collision probability negligible for this use case).
+     *
+     * @param body - The raw request body buffer
+     * @returns 16-character hex string
+     */
+    getRequestHash(body: Buffer): string;
+    /**
+     * Record a request from an agent to a specific endpoint with the given body hash.
+     * Prunes timestamps outside the current window for this agent+key combination.
+     *
+     * @param agentId - The agent making the request
+     * @param endpoint - The upstream endpoint path
+     * @param bodyHash - Hash of the request body (from getRequestHash)
+     */
+    recordRequest(agentId: string, endpoint: string, bodyHash: string): void;
+    /**
+     * Check if the given agent is currently looping based on the threshold.
+     * Must be called AFTER recordRequest for the same request.
+     *
+     * @param agentId - The agent to check
+     * @param endpoint - The upstream endpoint path
+     * @param bodyHash - Hash of the request body (from getRequestHash)
+     * @returns true if the agent has exceeded the loop detection threshold
+     */
+    isLooping(agentId: string, endpoint: string, bodyHash: string): boolean;
+    /**
+     * Get the loop detection config for a specific agent.
+     * Returns the agent's per-agent config if available, otherwise the default.
+     *
+     * @param agentId - The agent to look up
+     * @returns LoopDetectionConfig to use for this agent
+     */
+    getAgentConfig(agentId: string): LoopDetectionConfig;
+    /**
+     * Clear loop detection state for one or all agents.
+     *
+     * @param agentId - If provided, clears only this agent's data. Otherwise clears all.
+     */
+    clear(agentId?: string): void;
+}

package/dist/loop-detector.js

@@ -0,0 +1,122 @@
+/**
+ * Loop detection for the Govyn proxy server.
+ *
+ * Detects agents making repeated identical requests (same endpoint + same body hash)
+ * within a configurable time window. When the threshold is exceeded, the agent is
+ * flagged as looping and can be blocked via BudgetEnforcer.blockAgent().
+ *
+ * Sliding window implementation: per-agent, per-request-key array of timestamps.
+ * On each recordRequest, prune timestamps outside the window, then check count >= threshold.
+ */
+import * as crypto from 'node:crypto';
+/**
+ * LoopDetector tracks repeated identical requests per agent.
+ *
+ * Each "identical request" is identified by the combination of:
+ * - The upstream endpoint path
+ * - A hash of the request body (first 16 hex chars of SHA-256)
+ *
+ * When the same agent hits the same endpoint+bodyHash N times within M seconds,
+ * isLooping() returns true. Thresholds are configurable per agent.
+ */
+export class LoopDetector {
+    defaultConfig;
+    agentConfigs;
+    /** Map of agentId -> array of request windows (one per unique endpoint+bodyHash) */
+    windows;
+    constructor(defaultConfig, agentConfigs) {
+        this.defaultConfig = defaultConfig;
+        this.agentConfigs = agentConfigs;
+        this.windows = new Map();
+    }
+    /**
+     * Compute a compact hash of the request body for identity comparison.
+     *
+     * Uses SHA-256 truncated to 16 hex chars (64-bit) — sufficient for loop detection
+     * (collision probability negligible for this use case).
+     *
+     * @param body - The raw request body buffer
+     * @returns 16-character hex string
+     */
+    getRequestHash(body) {
+        return crypto.createHash('sha256').update(body).digest('hex').slice(0, 16);
+    }
+    /**
+     * Record a request from an agent to a specific endpoint with the given body hash.
+     * Prunes timestamps outside the current window for this agent+key combination.
+     *
+     * @param agentId - The agent making the request
+     * @param endpoint - The upstream endpoint path
+     * @param bodyHash - Hash of the request body (from getRequestHash)
+     */
+    recordRequest(agentId, endpoint, bodyHash) {
+        const config = this.getAgentConfig(agentId);
+        const windowMs = config.windowSeconds * 1000;
+        const now = Date.now();
+        const key = `${endpoint}:${bodyHash}`;
+        // Get or create windows array for this agent
+        if (!this.windows.has(agentId)) {
+            this.windows.set(agentId, []);
+        }
+        const agentWindows = this.windows.get(agentId);
+        // Find existing window for this key or create a new one
+        let window = agentWindows.find((w) => w.key === key);
+        if (!window) {
+            window = { key, timestamps: [] };
+            agentWindows.push(window);
+        }
+        // Add current timestamp
+        window.timestamps.push(now);
+        // Prune timestamps outside the window
+        const cutoff = now - windowMs;
+        window.timestamps = window.timestamps.filter((ts) => ts > cutoff);
+    }
+    /**
+     * Check if the given agent is currently looping based on the threshold.
+     * Must be called AFTER recordRequest for the same request.
+     *
+     * @param agentId - The agent to check
+     * @param endpoint - The upstream endpoint path
+     * @param bodyHash - Hash of the request body (from getRequestHash)
+     * @returns true if the agent has exceeded the loop detection threshold
+     */
+    isLooping(agentId, endpoint, bodyHash) {
+        const config = this.getAgentConfig(agentId);
+        const key = `${endpoint}:${bodyHash}`;
+        const agentWindows = this.windows.get(agentId);
+        if (!agentWindows)
+            return false;
+        const window = agentWindows.find((w) => w.key === key);
+        if (!window)
+            return false;
+        return window.timestamps.length >= config.threshold;
+    }
+    /**
+     * Get the loop detection config for a specific agent.
+     * Returns the agent's per-agent config if available, otherwise the default.
+     *
+     * @param agentId - The agent to look up
+     * @returns LoopDetectionConfig to use for this agent
+     */
+    getAgentConfig(agentId) {
+        const agentConfig = this.agentConfigs.get(agentId);
+        if (agentConfig?.loopDetection) {
+            return agentConfig.loopDetection;
+        }
+        return this.defaultConfig;
+    }
+    /**
+     * Clear loop detection state for one or all agents.
+     *
+     * @param agentId - If provided, clears only this agent's data. Otherwise clears all.
+     */
+    clear(agentId) {
+        if (agentId !== undefined) {
+            this.windows.delete(agentId);
+        }
+        else {
+            this.windows.clear();
+        }
+    }
+}
+//# sourceMappingURL=loop-detector.js.map

package/dist/loop-detector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loop-detector.js","sourceRoot":"","sources":["../src/loop-detector.ts"],"names":[],"mappings":"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"}

package/dist/persistence-types.d.ts

@@ -0,0 +1,165 @@
+import type { CostRecord } from './types.js';
+export interface PolicyEvaluationRecord {
+    agentId: string;
+    provider: string;
+    path: string;
+    allowed: boolean;
+    evaluatedCount: number;
+    matchedCount: number;
+    deniedBy?: string;
+    deniedReason?: string;
+    evaluationTimeMs?: number;
+}
+export interface ApprovalStatusRecord {
+    id: string;
+    status: 'pending' | 'approved' | 'denied' | 'denied_timeout';
+    approvalToken?: string;
+    decidedAt?: string;
+    expiresAt: string;
+}
+export interface ApprovalListEntry {
+    id: string;
+    agent_id: string;
+    provider: string;
+    model: string | null;
+    target_path: string;
+    policy_name: string;
+    estimated_cost: number | null;
+    request_summary: string | null;
+    status: 'pending' | 'approved' | 'denied' | 'denied_timeout';
+    decided_by: string | null;
+    decision_notes: string | null;
+    decided_at: string | null;
+    expires_at: string;
+    created_at: string;
+}
+export interface ApprovalListResult {
+    approvals: ApprovalListEntry[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+export interface ApprovalStore {
+    createApprovalRequest(params: {
+        agentId: string;
+        provider: string;
+        model?: string;
+        targetPath: string;
+        policyName: string;
+        policyRule?: string;
+        estimatedCost?: number;
+        requestSummary: string;
+        requestHash: string;
+        requestPayload?: unknown;
+        timeoutSeconds: number;
+    }): Promise<{
+        id: string;
+        pollingUrl: string;
+        expiresAt: string;
+    }>;
+    getApprovalStatus(id: string): Promise<ApprovalStatusRecord | null>;
+    validateAndConsumeToken(token: string, expected: {
+        agentId: string;
+        targetPath: string;
+        requestHash: string;
+    }): Promise<{
+        policyName: string;
+    } | null>;
+    approveRequest(id: string, decidedBy: string, notes?: string): Promise<boolean>;
+    denyRequest(id: string, decidedBy: string, notes?: string): Promise<boolean>;
+    listApprovals(statusFilters: string[], limit: number, offset: number, agentId: string | null): Promise<ApprovalListResult>;
+    expireTimedOutApprovals(now?: Date): Promise<number>;
+}
+export interface BudgetThresholdConfig {
+    agent_id: string;
+    metric: 'daily' | 'monthly';
+    threshold_percent: number;
+}
+export interface PolicyTriggerConfig {
+    policy_name: string;
+    agent_id: string;
+}
+export interface AlertRuleRecord {
+    id: string;
+    name: string;
+    type: 'budget_threshold' | 'policy_trigger';
+    enabled: boolean;
+    config: BudgetThresholdConfig | PolicyTriggerConfig;
+    webhookUrl: string;
+    cooldownMinutes: number;
+    lastFiredAt: Date | null;
+    createdAt: Date;
+    updatedAt: Date;
+}
+export interface AlertHistoryEntry {
+    id: string;
+    rule_id: string;
+    rule_name: string;
+    rule_type: string;
+    event_type: string;
+    event_payload: Record<string, unknown>;
+    webhook_url: string;
+    webhook_status: number | null;
+    webhook_error: string | null;
+    fired_at: string;
+}
+export interface AlertHistoryResult {
+    alerts: AlertHistoryEntry[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+export interface AlertStore {
+    listRules(): Promise<AlertRuleRecord[]>;
+    createRule(input: {
+        name: string;
+        type: 'budget_threshold' | 'policy_trigger';
+        enabled: boolean;
+        config: BudgetThresholdConfig | PolicyTriggerConfig;
+        webhookUrl: string;
+        cooldownMinutes: number;
+    }): Promise<AlertRuleRecord>;
+    updateRule(input: {
+        id: string;
+        name?: string;
+        enabled?: boolean;
+        config?: BudgetThresholdConfig | PolicyTriggerConfig;
+        webhookUrl?: string;
+        cooldownMinutes?: number;
+    }): Promise<AlertRuleRecord | null>;
+    deleteRule(id: string): Promise<boolean>;
+    listHistory(limit: number, offset: number, ruleId?: string | null): Promise<AlertHistoryResult>;
+    recordAlertHistory(input: {
+        ruleId: string;
+        ruleName: string;
+        ruleType: string;
+        eventType: string;
+        eventPayload: Record<string, unknown>;
+        webhookUrl: string;
+        webhookStatus: number | null;
+        webhookError: string | null;
+    }): Promise<void>;
+    touchRuleLastFired(id: string, firedAt: Date): Promise<void>;
+}
+export interface PersistenceWriterStore {
+    insertCostRecord(record: CostRecord): Promise<void>;
+    insertPolicyEvaluation(record: PolicyEvaluationRecord): Promise<void>;
+    insertApprovalEvent(event: {
+        requestId: string;
+        action: 'created' | 'approved' | 'denied' | 'denied_timeout' | 'token_consumed';
+        decidedBy?: string;
+        notes?: string;
+    }): Promise<void>;
+    ping(): Promise<void>;
+}
+export interface RetentionStore {
+    cleanupCostRecords(cutoff: Date): Promise<{
+        aggregated: number;
+        deleted: number;
+    }>;
+    cleanupPolicyEvaluations(cutoff: Date): Promise<number>;
+    cleanupApprovalRecords(cutoff: Date): Promise<number>;
+}
+export interface PersistenceCloser {
+    close(): Promise<void>;
+}

package/dist/persistence-types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=persistence-types.js.map

package/dist/persistence-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"persistence-types.js","sourceRoot":"","sources":["../src/persistence-types.ts"],"names":[],"mappings":""}

package/dist/persistence.d.ts

@@ -0,0 +1,185 @@
+import type Database from 'better-sqlite3';
+import postgres from 'postgres';
+import type { AlertHistoryResult, AlertRuleRecord, ApprovalListResult, ApprovalStatusRecord, ApprovalStore, AlertStore, PersistenceCloser, PersistenceWriterStore, PolicyEvaluationRecord, RetentionStore } from './persistence-types.js';
+import type { CostRecord, DatabaseConfig } from './types.js';
+type AlertRuleType = 'budget_threshold' | 'policy_trigger';
+export interface PersistenceBackend extends ApprovalStore, AlertStore, PersistenceWriterStore, RetentionStore, PersistenceCloser {
+    readonly kind: 'sqlite' | 'postgres';
+    readonly url: string;
+}
+export declare function isPostgresSql(value: unknown): value is postgres.Sql;
+export declare class PostgresPersistence implements PersistenceBackend {
+    private readonly sql;
+    readonly url: string;
+    private readonly retentionDays;
+    private readonly approvalRetentionDays;
+    readonly kind: "postgres";
+    constructor(sql: postgres.Sql, url: string, retentionDays: number, approvalRetentionDays: number);
+    static connect(config: DatabaseConfig): Promise<PostgresPersistence>;
+    close(): Promise<void>;
+    ping(): Promise<void>;
+    insertCostRecord(record: CostRecord): Promise<void>;
+    insertPolicyEvaluation(record: PolicyEvaluationRecord): Promise<void>;
+    insertApprovalEvent(event: {
+        requestId: string;
+        action: 'created' | 'approved' | 'denied' | 'denied_timeout' | 'token_consumed';
+        decidedBy?: string;
+        notes?: string;
+    }): Promise<void>;
+    createApprovalRequest(params: {
+        agentId: string;
+        provider: string;
+        model?: string;
+        targetPath: string;
+        policyName: string;
+        policyRule?: string;
+        estimatedCost?: number;
+        requestSummary: string;
+        requestHash: string;
+        requestPayload?: unknown;
+        timeoutSeconds: number;
+    }): Promise<{
+        id: string;
+        pollingUrl: string;
+        expiresAt: string;
+    }>;
+    getApprovalStatus(id: string): Promise<ApprovalStatusRecord | null>;
+    validateAndConsumeToken(token: string, expected: {
+        agentId: string;
+        targetPath: string;
+        requestHash: string;
+    }): Promise<{
+        policyName: string;
+    } | null>;
+    approveRequest(id: string, decidedBy: string, notes?: string): Promise<boolean>;
+    denyRequest(id: string, decidedBy: string, notes?: string): Promise<boolean>;
+    listApprovals(statusFilters: string[], limit: number, offset: number, agentId: string | null): Promise<ApprovalListResult>;
+    expireTimedOutApprovals(now?: Date): Promise<number>;
+    listRules(): Promise<AlertRuleRecord[]>;
+    createRule(input: {
+        name: string;
+        type: AlertRuleType;
+        enabled: boolean;
+        config: AlertRuleRecord['config'];
+        webhookUrl: string;
+        cooldownMinutes: number;
+    }): Promise<AlertRuleRecord>;
+    updateRule(input: {
+        id: string;
+        name?: string;
+        enabled?: boolean;
+        config?: AlertRuleRecord['config'];
+        webhookUrl?: string;
+        cooldownMinutes?: number;
+    }): Promise<AlertRuleRecord | null>;
+    deleteRule(id: string): Promise<boolean>;
+    listHistory(limit: number, offset: number, ruleId?: string | null): Promise<AlertHistoryResult>;
+    recordAlertHistory(input: {
+        ruleId: string;
+        ruleName: string;
+        ruleType: string;
+        eventType: string;
+        eventPayload: Record<string, unknown>;
+        webhookUrl: string;
+        webhookStatus: number | null;
+        webhookError: string | null;
+    }): Promise<void>;
+    touchRuleLastFired(id: string, firedAt: Date): Promise<void>;
+    cleanupCostRecords(cutoff: Date): Promise<{
+        aggregated: number;
+        deleted: number;
+    }>;
+    cleanupPolicyEvaluations(cutoff: Date): Promise<number>;
+    cleanupApprovalRecords(cutoff: Date): Promise<number>;
+}
+export declare class SqlitePersistence implements PersistenceBackend {
+    private readonly db;
+    readonly url: string;
+    private readonly retentionDays;
+    private readonly approvalRetentionDays;
+    readonly kind: "sqlite";
+    constructor(db: Database.Database, url: string, retentionDays: number, approvalRetentionDays: number);
+    static connect(config: DatabaseConfig): Promise<SqlitePersistence>;
+    close(): Promise<void>;
+    ping(): Promise<void>;
+    insertCostRecord(record: CostRecord): Promise<void>;
+    insertPolicyEvaluation(record: PolicyEvaluationRecord): Promise<void>;
+    insertApprovalEvent(event: {
+        requestId: string;
+        action: 'created' | 'approved' | 'denied' | 'denied_timeout' | 'token_consumed';
+        decidedBy?: string;
+        notes?: string;
+    }): Promise<void>;
+    createApprovalRequest(params: {
+        agentId: string;
+        provider: string;
+        model?: string;
+        targetPath: string;
+        policyName: string;
+        policyRule?: string;
+        estimatedCost?: number;
+        requestSummary: string;
+        requestHash: string;
+        requestPayload?: unknown;
+        timeoutSeconds: number;
+    }): Promise<{
+        id: string;
+        pollingUrl: string;
+        expiresAt: string;
+    }>;
+    getApprovalStatus(id: string): Promise<ApprovalStatusRecord | null>;
+    validateAndConsumeToken(token: string, expected: {
+        agentId: string;
+        targetPath: string;
+        requestHash: string;
+    }): Promise<{
+        policyName: string;
+    } | null>;
+    approveRequest(id: string, decidedBy: string, notes?: string): Promise<boolean>;
+    denyRequest(id: string, decidedBy: string, notes?: string): Promise<boolean>;
+    listApprovals(statusFilters: string[], limit: number, offset: number, agentId: string | null): Promise<ApprovalListResult>;
+    expireTimedOutApprovals(now?: Date): Promise<number>;
+    listRules(): Promise<AlertRuleRecord[]>;
+    createRule(input: {
+        name: string;
+        type: AlertRuleType;
+        enabled: boolean;
+        config: AlertRuleRecord['config'];
+        webhookUrl: string;
+        cooldownMinutes: number;
+    }): Promise<AlertRuleRecord>;
+    updateRule(input: {
+        id: string;
+        name?: string;
+        enabled?: boolean;
+        config?: AlertRuleRecord['config'];
+        webhookUrl?: string;
+        cooldownMinutes?: number;
+    }): Promise<AlertRuleRecord | null>;
+    deleteRule(id: string): Promise<boolean>;
+    listHistory(limit: number, offset: number, ruleId?: string | null): Promise<AlertHistoryResult>;
+    recordAlertHistory(input: {
+        ruleId: string;
+        ruleName: string;
+        ruleType: string;
+        eventType: string;
+        eventPayload: Record<string, unknown>;
+        webhookUrl: string;
+        webhookStatus: number | null;
+        webhookError: string | null;
+    }): Promise<void>;
+    touchRuleLastFired(id: string, firedAt: Date): Promise<void>;
+    cleanupCostRecords(cutoff: Date): Promise<{
+        aggregated: number;
+        deleted: number;
+    }>;
+    cleanupPolicyEvaluations(cutoff: Date): Promise<number>;
+    cleanupApprovalRecords(cutoff: Date): Promise<number>;
+    private getRuleById;
+}
+export declare function createPersistenceBackend(config: DatabaseConfig): Promise<PersistenceBackend>;
+export declare function adaptApprovalStore(input: ApprovalStore | postgres.Sql): ApprovalStore;
+export declare function adaptAlertStore(input: AlertStore | postgres.Sql): AlertStore;
+export declare function adaptWriterStore(input: PersistenceWriterStore | postgres.Sql): PersistenceWriterStore;
+export declare function adaptRetentionStore(input: RetentionStore | postgres.Sql, retentionDays: number, approvalRetentionDays: number): RetentionStore;
+export {};