clodds 1.1.0

package/dist/history/index.js

@@ -0,0 +1,362 @@
+"use strict";
+/**
+ * Trade History Service - Fetch and analyze trade history
+ *
+ * Features:
+ * - Fetch trades from Polymarket/Kalshi APIs
+ * - Calculate daily/weekly/monthly PnL
+ * - Win rate and performance metrics
+ * - Store in SQLite for persistence
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTradeHistoryService = createTradeHistoryService;
+const logger_1 = require("../utils/logger");
+const polymarket_auth_1 = require("../utils/polymarket-auth");
+const kalshi_auth_1 = require("../utils/kalshi-auth");
+// =============================================================================
+// POLYMARKET API
+// =============================================================================
+const POLY_CLOB_URL = 'https://clob.polymarket.com';
+async function fetchPolymarketTrades(auth, limit = 100) {
+    const url = `${POLY_CLOB_URL}/trades?limit=${limit}`;
+    const headers = (0, polymarket_auth_1.buildPolymarketHeadersForUrl)(auth, 'GET', url);
+    try {
+        const response = await fetch(url, {
+            method: 'GET',
+            headers: {
+                ...headers,
+                'Content-Type': 'application/json',
+            },
+        });
+        if (!response.ok) {
+            logger_1.logger.error({ status: response.status }, 'Failed to fetch Polymarket trades');
+            return [];
+        }
+        const data = (await response.json());
+        return data.map((t) => {
+            const shares = parseFloat(t.size);
+            const price = parseFloat(t.price);
+            const feeRate = parseFloat(t.fee_rate_bps || '0') / 10000;
+            const value = shares * price;
+            const fee = value * feeRate;
+            return {
+                id: `poly_${t.id}`,
+                platform: 'polymarket',
+                marketId: t.market,
+                outcome: t.outcome || 'Unknown',
+                side: t.side.toLowerCase(),
+                shares,
+                price,
+                value,
+                fee,
+                timestamp: new Date(t.match_time || t.created_at),
+                transactionHash: t.transaction_hash,
+            };
+        });
+    }
+    catch (error) {
+        logger_1.logger.error({ error }, 'Error fetching Polymarket trades');
+        return [];
+    }
+}
+// =============================================================================
+// KALSHI API
+// =============================================================================
+const KALSHI_API_URL = 'https://api.elections.kalshi.com/trade-api/v2';
+async function fetchKalshiTrades(auth, limit = 100) {
+    const url = `${KALSHI_API_URL}/portfolio/fills?limit=${limit}`;
+    const headers = (0, kalshi_auth_1.buildKalshiHeadersForUrl)(auth, 'GET', url);
+    try {
+        const response = await fetch(url, {
+            method: 'GET',
+            headers: {
+                ...headers,
+                'Content-Type': 'application/json',
+            },
+        });
+        if (!response.ok) {
+            logger_1.logger.error({ status: response.status }, 'Failed to fetch Kalshi trades');
+            return [];
+        }
+        const data = (await response.json());
+        return (data.fills || []).map((t) => {
+            const price = (t.side === 'yes' ? t.yes_price : t.no_price) / 100;
+            const shares = t.count;
+            const value = shares * price;
+            return {
+                id: `kalshi_${t.trade_id}`,
+                platform: 'kalshi',
+                marketId: t.ticker,
+                marketQuestion: t.market_title,
+                outcome: t.side === 'yes' ? 'Yes' : 'No',
+                side: t.action,
+                shares,
+                price,
+                value,
+                fee: 0, // Kalshi fees are in spread
+                timestamp: new Date(t.created_time),
+                orderId: t.order_id,
+            };
+        });
+    }
+    catch (error) {
+        logger_1.logger.error({ error }, 'Error fetching Kalshi trades');
+        return [];
+    }
+}
+// =============================================================================
+// TRADE HISTORY SERVICE
+// =============================================================================
+function createTradeHistoryService(config, db) {
+    const trades = [];
+    // Initialize database table if provided
+    if (db) {
+        db.run(`
+      CREATE TABLE IF NOT EXISTS trade_history (
+        id TEXT PRIMARY KEY,
+        platform TEXT NOT NULL,
+        marketId TEXT NOT NULL,
+        marketQuestion TEXT,
+        outcome TEXT NOT NULL,
+        side TEXT NOT NULL,
+        shares REAL NOT NULL,
+        price REAL NOT NULL,
+        value REAL NOT NULL,
+        fee REAL NOT NULL,
+        timestamp TEXT NOT NULL,
+        orderId TEXT,
+        transactionHash TEXT
+      )
+    `);
+        db.run(`CREATE INDEX IF NOT EXISTS idx_trades_timestamp ON trade_history(timestamp)`);
+        db.run(`CREATE INDEX IF NOT EXISTS idx_trades_platform ON trade_history(platform)`);
+        // Load existing trades from database
+        try {
+            const rows = db.query('SELECT * FROM trade_history ORDER BY timestamp DESC LIMIT 1000');
+            for (const row of rows) {
+                trades.push({
+                    ...row,
+                    timestamp: new Date(row.timestamp),
+                });
+            }
+            logger_1.logger.info({ count: trades.length }, 'Loaded trades from database');
+        }
+        catch (err) {
+            logger_1.logger.debug('No existing trades in database');
+        }
+    }
+    function getStartOfPeriod(period) {
+        const now = new Date();
+        switch (period) {
+            case 'day':
+                return new Date(now.getFullYear(), now.getMonth(), now.getDate());
+            case 'week':
+                const dayOfWeek = now.getDay();
+                const startOfWeek = new Date(now);
+                startOfWeek.setDate(now.getDate() - dayOfWeek);
+                startOfWeek.setHours(0, 0, 0, 0);
+                return startOfWeek;
+            case 'month':
+                return new Date(now.getFullYear(), now.getMonth(), 1);
+            case 'all':
+            default:
+                return new Date(0);
+        }
+    }
+    const service = {
+        async fetchTrades(limit = 100) {
+            const allTrades = [];
+            if (config.polymarket) {
+                const polyTrades = await fetchPolymarketTrades(config.polymarket, limit);
+                allTrades.push(...polyTrades);
+            }
+            if (config.kalshi) {
+                const kalshiTrades = await fetchKalshiTrades(config.kalshi, limit);
+                allTrades.push(...kalshiTrades);
+            }
+            // Sort by timestamp descending
+            allTrades.sort((a, b) => b.timestamp.getTime() - a.timestamp.getTime());
+            // Merge with existing trades (dedupe by ID)
+            const existingIds = new Set(trades.map((t) => t.id));
+            for (const trade of allTrades) {
+                if (!existingIds.has(trade.id)) {
+                    trades.unshift(trade);
+                    existingIds.add(trade.id);
+                }
+            }
+            // Keep sorted
+            trades.sort((a, b) => b.timestamp.getTime() - a.timestamp.getTime());
+            logger_1.logger.info({ fetched: allTrades.length, total: trades.length }, 'Fetched trades');
+            return allTrades;
+        },
+        getTrades(filters) {
+            let result = [...trades];
+            if (filters?.platform) {
+                result = result.filter((t) => t.platform === filters.platform);
+            }
+            if (filters?.marketId) {
+                result = result.filter((t) => t.marketId === filters.marketId);
+            }
+            if (filters?.side) {
+                result = result.filter((t) => t.side === filters.side);
+            }
+            if (filters?.startDate) {
+                result = result.filter((t) => t.timestamp >= filters.startDate);
+            }
+            if (filters?.endDate) {
+                result = result.filter((t) => t.timestamp <= filters.endDate);
+            }
+            if (filters?.limit) {
+                result = result.slice(0, filters.limit);
+            }
+            return result;
+        },
+        getTradeById(id) {
+            return trades.find((t) => t.id === id) || null;
+        },
+        async syncToDatabase() {
+            if (!db)
+                return 0;
+            let synced = 0;
+            for (const trade of trades) {
+                try {
+                    db.run(`INSERT OR REPLACE INTO trade_history
+             (id, platform, marketId, marketQuestion, outcome, side, shares, price, value, fee, timestamp, orderId, transactionHash)
+             VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
+                        trade.id,
+                        trade.platform,
+                        trade.marketId,
+                        trade.marketQuestion || null,
+                        trade.outcome,
+                        trade.side,
+                        trade.shares,
+                        trade.price,
+                        trade.value,
+                        trade.fee,
+                        trade.timestamp.toISOString(),
+                        trade.orderId || null,
+                        trade.transactionHash || null,
+                    ]);
+                    synced++;
+                }
+                catch (err) {
+                    logger_1.logger.warn({ error: err, tradeId: trade.id }, 'Failed to sync trade');
+                }
+            }
+            logger_1.logger.info({ synced }, 'Synced trades to database');
+            return synced;
+        },
+        getDailyPnL(days = 30) {
+            const result = [];
+            const now = new Date();
+            for (let i = 0; i < days; i++) {
+                const date = new Date(now);
+                date.setDate(date.getDate() - i);
+                const dateStr = date.toISOString().slice(0, 10);
+                const dayTrades = trades.filter((t) => t.timestamp.toISOString().slice(0, 10) === dateStr);
+                // Simplified PnL calculation (buys negative, sells positive)
+                const pnl = dayTrades.reduce((sum, t) => {
+                    return sum + (t.side === 'sell' ? t.value : -t.value) - t.fee;
+                }, 0);
+                const volume = dayTrades.reduce((sum, t) => sum + t.value, 0);
+                result.push({
+                    date: dateStr,
+                    pnl,
+                    trades: dayTrades.length,
+                    volume,
+                });
+            }
+            return result.reverse();
+        },
+        getStats(period = 'all') {
+            const startDate = getStartOfPeriod(period);
+            const periodTrades = trades.filter((t) => t.timestamp >= startDate);
+            // Group trades by market to calculate per-market PnL
+            const marketPnL = new Map();
+            for (const trade of periodTrades) {
+                const key = `${trade.platform}_${trade.marketId}_${trade.outcome}`;
+                const current = marketPnL.get(key) || 0;
+                const tradeValue = trade.side === 'sell' ? trade.value : -trade.value;
+                marketPnL.set(key, current + tradeValue - trade.fee);
+            }
+            const pnlValues = Array.from(marketPnL.values());
+            const wins = pnlValues.filter((p) => p > 0);
+            const losses = pnlValues.filter((p) => p < 0);
+            const totalWins = wins.reduce((sum, p) => sum + p, 0);
+            const totalLosses = Math.abs(losses.reduce((sum, p) => sum + p, 0));
+            return {
+                totalTrades: periodTrades.length,
+                winningTrades: wins.length,
+                losingTrades: losses.length,
+                winRate: pnlValues.length > 0 ? (wins.length / pnlValues.length) * 100 : 0,
+                totalVolume: periodTrades.reduce((sum, t) => sum + t.value, 0),
+                totalPnL: pnlValues.reduce((sum, p) => sum + p, 0),
+                avgWin: wins.length > 0 ? totalWins / wins.length : 0,
+                avgLoss: losses.length > 0 ? totalLosses / losses.length : 0,
+                profitFactor: totalLosses > 0 ? totalWins / totalLosses : totalWins > 0 ? Infinity : 0,
+                largestWin: wins.length > 0 ? Math.max(...wins) : 0,
+                largestLoss: losses.length > 0 ? Math.min(...losses) : 0,
+            };
+        },
+        getTodayPnL() {
+            const today = new Date();
+            today.setHours(0, 0, 0, 0);
+            return trades
+                .filter((t) => t.timestamp >= today)
+                .reduce((sum, t) => {
+                return sum + (t.side === 'sell' ? t.value : -t.value) - t.fee;
+            }, 0);
+        },
+        getTotalPnL() {
+            const stats = this.getStats('all');
+            return stats.totalPnL;
+        },
+        formatRecentTrades(limit = 10) {
+            const recent = trades.slice(0, limit);
+            if (recent.length === 0) {
+                return '📭 No recent trades';
+            }
+            let text = `📜 **Recent Trades** (${recent.length})\n\n`;
+            for (const trade of recent) {
+                const sideEmoji = trade.side === 'buy' ? '🟢' : '🔴';
+                const time = trade.timestamp.toLocaleTimeString();
+                const question = trade.marketQuestion
+                    ? trade.marketQuestion.slice(0, 30) + (trade.marketQuestion.length > 30 ? '...' : '')
+                    : trade.marketId.slice(0, 15);
+                text += `${sideEmoji} **${trade.side.toUpperCase()}** ${trade.shares.toFixed(2)} ${trade.outcome}\n`;
+                text += `   ${question}\n`;
+                text += `   $${trade.price.toFixed(3)} × ${trade.shares.toFixed(2)} = $${trade.value.toFixed(2)}\n`;
+                text += `   _${time}_\n\n`;
+            }
+            return text;
+        },
+        formatStats() {
+            const stats = this.getStats('all');
+            const todayStats = this.getStats('day');
+            const weekStats = this.getStats('week');
+            let text = `📊 **Trading Statistics**\n\n`;
+            text += `**All Time:**\n`;
+            text += `  Trades: ${stats.totalTrades}\n`;
+            text += `  Win Rate: ${stats.winRate.toFixed(1)}%\n`;
+            text += `  Total PnL: $${stats.totalPnL.toFixed(2)}\n`;
+            text += `  Volume: $${stats.totalVolume.toFixed(2)}\n\n`;
+            text += `**This Week:**\n`;
+            text += `  Trades: ${weekStats.totalTrades}\n`;
+            text += `  PnL: $${weekStats.totalPnL.toFixed(2)}\n\n`;
+            text += `**Today:**\n`;
+            text += `  Trades: ${todayStats.totalTrades}\n`;
+            text += `  PnL: $${todayStats.totalPnL.toFixed(2)}\n\n`;
+            if (stats.totalTrades > 0) {
+                text += `**Performance:**\n`;
+                text += `  Avg Win: $${stats.avgWin.toFixed(2)}\n`;
+                text += `  Avg Loss: $${stats.avgLoss.toFixed(2)}\n`;
+                text += `  Profit Factor: ${stats.profitFactor === Infinity ? '∞' : stats.profitFactor.toFixed(2)}\n`;
+                text += `  Largest Win: $${stats.largestWin.toFixed(2)}\n`;
+                text += `  Largest Loss: $${stats.largestLoss.toFixed(2)}\n`;
+            }
+            return text;
+        },
+    };
+    return service;
+}
+//# sourceMappingURL=index.js.map

package/dist/history/index.js.map

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

package/dist/hooks/index.d.ts

@@ -0,0 +1,279 @@
+/**
+ * Hooks System - Clawdbot-style event hooks with full lifecycle support
+ *
+ * Features:
+ * - Register hooks for events (message, response, tool, agent, gateway, etc.)
+ * - Sync and async hooks
+ * - Hook priorities (higher runs first)
+ * - Hook filtering by channel/user
+ * - Result-returning hooks (can modify events)
+ * - Tool interception (before/after tool calls)
+ * - Message modification capability
+ * - Gateway and agent lifecycle hooks
+ * - Hook discovery from filesystem
+ * - Eligibility checking (requirements validation)
+ */
+import type { IncomingMessage, OutgoingMessage, Session } from '../types';
+export type HookEvent = 'message:before' | 'message:after' | 'message:received' | 'message:sending' | 'message:sent' | 'response:before' | 'response:after' | 'session:start' | 'session:end' | 'session:reset' | 'session:created' | 'agent:before_start' | 'agent:end' | 'compaction:before' | 'compaction:after' | 'tool:before_call' | 'tool:after_call' | 'tool:result_persist' | 'gateway:start' | 'gateway:stop' | 'error';
+export interface HookContext {
+    event: HookEvent;
+    message?: IncomingMessage;
+    response?: OutgoingMessage;
+    session?: Session;
+    error?: Error;
+    toolName?: string;
+    toolParams?: Record<string, unknown>;
+    runId?: string;
+    abortSignal?: AbortSignal;
+    cancelledReason?: string;
+    hookId?: string;
+    hookName?: string;
+    hookStateKey?: string;
+    getState?: (key: string, defaultValue?: unknown) => unknown;
+    setState?: (key: string, value: unknown) => void;
+    clearState?: (key?: string) => void;
+    /** Set to true to stop further processing */
+    cancelled?: boolean;
+    /** Custom data passed between hooks */
+    data: Record<string, unknown>;
+}
+/** Context for agent hooks */
+export interface AgentHookContext extends HookContext {
+    agentId: string;
+    sessionId?: string;
+    /** System prompt (can be modified by before_agent_start) */
+    systemPrompt?: string;
+    /** Content to prepend to context */
+    prependContext?: string;
+    /** Messages in the conversation */
+    messages?: Array<{
+        role: string;
+        content: string;
+    }>;
+}
+/** Context for tool hooks */
+export interface ToolHookContext extends HookContext {
+    toolName: string;
+    toolParams: Record<string, unknown>;
+    /** Set to true to block tool execution */
+    blocked?: boolean;
+    /** Reason for blocking */
+    blockReason?: string;
+    /** Tool result (for after_call and result_persist) */
+    toolResult?: unknown;
+    /** Modified result (for result_persist) */
+    modifiedResult?: unknown;
+}
+/** Context for message sending hooks */
+export interface MessageSendingContext extends HookContext {
+    /** Original content */
+    content: string;
+    /** Modified content (if changed) */
+    modifiedContent?: string;
+    /** Channel to send to */
+    channel: string;
+    /** Recipient */
+    recipient?: string;
+    /** Set to true to cancel sending */
+    cancel?: boolean;
+}
+/** Context for compaction hooks */
+export interface CompactionContext extends HookContext {
+    sessionId: string;
+    /** Token count before compaction */
+    tokensBefore?: number;
+    /** Token count after compaction */
+    tokensAfter?: number;
+    /** Compaction count (how many times compacted) */
+    compactionCount: number;
+}
+/** Result from before_agent_start hook */
+export interface AgentStartResult {
+    systemPrompt?: string;
+    prependContext?: string;
+}
+/** Result from message_sending hook */
+export interface MessageSendingResult {
+    content?: string;
+    cancel?: boolean;
+}
+/** Result from before_tool_call hook */
+export interface ToolCallResult {
+    params?: Record<string, unknown>;
+    block?: boolean;
+    blockReason?: string;
+}
+/** Result from tool_result_persist hook */
+export interface ToolPersistResult {
+    message?: unknown;
+}
+export type HookFn<TContext = HookContext, TResult = void> = (ctx: TContext) => Promise<TResult | void> | TResult | void;
+export interface Hook<TContext = HookContext, TResult = void> {
+    id: string;
+    name?: string;
+    event: HookEvent;
+    fn: HookFn<TContext, TResult>;
+    priority: number;
+    /** Execution mode: sequential (for modifying) or parallel (fire-and-forget) */
+    execution: 'sequential' | 'parallel';
+    /** Whether this hook is sync-only (like tool_result_persist) */
+    syncOnly?: boolean;
+    filter?: {
+        channels?: string[];
+        users?: string[];
+        agentIds?: string[];
+        tools?: string[];
+    };
+    /** Conditional execution */
+    when?: HookCondition;
+    /** Requirements for this hook to be active */
+    requirements?: HookRequirements;
+    /** Whether hook is enabled */
+    enabled: boolean;
+    /** Source path (for discovered hooks) */
+    sourcePath?: string;
+}
+export interface HookRequirements {
+    /** Required binaries in PATH */
+    bins?: string[];
+    /** Required environment variables */
+    env?: string[];
+    /** Required config keys */
+    config?: string[];
+    /** Required OS */
+    os?: string[];
+}
+export type HookCondition = {
+    any?: HookCondition[];
+    all?: HookCondition[];
+    not?: HookCondition;
+} | {
+    field: 'channel' | 'userId' | 'agentId' | 'toolName' | 'messageText' | 'event';
+    op: 'eq' | 'neq' | 'in' | 'contains' | 'regex' | 'startsWith' | 'endsWith';
+    value: string | string[];
+};
+export interface HookMetadata {
+    name: string;
+    version: string;
+    description?: string;
+    author?: string;
+    events: HookEvent[];
+    priority?: number;
+    execution?: 'sequential' | 'parallel';
+    requirements?: HookRequirements;
+}
+export interface HookStateFile {
+    version: number;
+    sources: Record<string, {
+        enabled: boolean;
+        updatedAt: string;
+    }>;
+}
+export interface HookStateStore {
+    version: number;
+    data: Record<string, Record<string, unknown>>;
+    updatedAt?: string;
+}
+export interface HookTraceEntry {
+    id: string;
+    hookId: string;
+    hookName?: string;
+    event: HookEvent;
+    execution: 'sequential' | 'parallel';
+    startedAt: string;
+    durationMs: number;
+    status: 'ok' | 'error';
+    error?: string;
+}
+export interface HookRunInfo {
+    runId: string;
+    event: HookEvent;
+    startedAt: string;
+    cancelled: boolean;
+    reason?: string;
+}
+export interface HooksService {
+    /** Register a hook */
+    register<TContext extends HookContext = HookContext, TResult = void>(event: HookEvent, fn: HookFn<TContext, TResult>, opts?: {
+        name?: string;
+        priority?: number;
+        execution?: 'sequential' | 'parallel';
+        syncOnly?: boolean;
+        filter?: Hook['filter'];
+        requirements?: HookRequirements;
+        sourcePath?: string;
+        when?: HookCondition;
+    }): string;
+    /** Unregister a hook */
+    unregister(id: string): boolean;
+    /** Enable/disable a hook */
+    setEnabled(id: string, enabled: boolean): boolean;
+    /** Trigger event (fire-and-forget for parallel hooks) */
+    trigger(event: HookEvent, ctx: Partial<HookContext>): Promise<HookContext>;
+    /** Trigger event with result collection (for modifying hooks) */
+    triggerWithResult<TResult>(event: HookEvent, ctx: Partial<HookContext>, mergeResults?: (results: TResult[]) => TResult): Promise<{
+        ctx: HookContext;
+        result: TResult | undefined;
+    }>;
+    /** Trigger sync hooks only (for hot paths like tool_result_persist) */
+    triggerSync(event: HookEvent, ctx: Partial<HookContext>): HookContext;
+    /** List all registered hooks */
+    list(): Hook[];
+    /** Get hook by ID */
+    get(id: string): Hook | undefined;
+    /** Check if hook requirements are met */
+    checkRequirements(requirements: HookRequirements): {
+        met: boolean;
+        missing: string[];
+    };
+    /** Discover hooks from directories */
+    discover(directories: string[]): Promise<number>;
+    /** Install a hook from path */
+    install(hookPath: string): Promise<string>;
+    /** Enable/disable hook tracing */
+    setTracingEnabled(enabled: boolean): void;
+    /** Set trace buffer limit */
+    setTraceLimit(limit: number): void;
+    /** List recent hook traces */
+    listTraces(limit?: number): HookTraceEntry[];
+    /** Clear hook traces */
+    clearTraces(): void;
+    /** Cancel a running hook execution */
+    cancel(runId: string, reason?: string): boolean;
+    /** List running hook executions */
+    listActiveRuns(): HookRunInfo[];
+    /** Get hook state */
+    getState(hookKey: string, key?: string): unknown;
+    /** Set hook state */
+    setState(hookKey: string, key: string, value: unknown): void;
+    /** Clear hook state */
+    clearState(hookKey: string, key?: string): void;
+}
+export declare function createHooksService(): HooksService;
+/**
+ * Create a tool interception hook
+ */
+export declare function createToolHook(service: HooksService, toolName: string | RegExp, handlers: {
+    before?: (ctx: ToolHookContext) => Promise<ToolCallResult | void> | ToolCallResult | void;
+    after?: (ctx: ToolHookContext) => Promise<void> | void;
+}): string[];
+/**
+ * Create a message filter hook
+ */
+export declare function createMessageFilter(service: HooksService, filter: (ctx: MessageSendingContext) => boolean, transform?: (content: string, ctx: MessageSendingContext) => string): string;
+/**
+ * Create an agent system prompt injector
+ */
+export declare function createSystemPromptInjector(service: HooksService, inject: (ctx: AgentHookContext) => string | undefined): string;
+export declare const hooks: HooksService;
+export declare function getHooksDir(): string;
+export declare function getHooksStatePath(): string;
+export declare function getHookStateStorePath(): string;
+export declare function resolveHookStateKey(input: string): string;
+export declare function loadHookStateStore(pathOverride?: string): HookStateStore;
+export declare function saveHookStateStore(pathOverride: string | undefined, store: HookStateStore): void;
+export declare function loadHooksState(): HookStateFile;
+export declare function saveHooksState(state: HookStateFile): void;
+export declare function getHookSourceEnabled(sourcePath: string): boolean | undefined;
+export declare function setHookSourceEnabled(sourcePath: string, enabled: boolean): void;
+export declare function removeHookSourceState(sourcePath: string): void;