agentseal 0.3.2 → 0.4.0

package/dist/index.d.cts

@@ -293,6 +293,59 @@ declare function buildExtractionProbes(): Probe[];
 
 declare function buildInjectionProbes(): Probe[];
 
+/**
+ * Custom probe loader — YAML/JSON probe definitions from files and directories.
+ *
+ * Port of Python agentseal/probes/loader.py.
+ */
+declare function validateProbe(probe: Record<string, any>, source: string): string[];
+declare function buildProbe(raw: Record<string, any>): Record<string, any>;
+declare function parseProbeFile(filePath: string): Array<Record<string, any>>;
+/**
+ * Load custom probes from a YAML/JSON file or directory.
+ *
+ * @param path Path to a .yaml/.json file or directory containing them.
+ * @returns List of validated probe dicts.
+ */
+declare function loadCustomProbes(path: string): Array<Record<string, any>>;
+/**
+ * Auto-discover probes from ~/.agentseal/probes/ and .agentseal/probes/.
+ *
+ * @returns Combined list of probes from both locations.
+ */
+declare function loadAllCustomProbes(): Array<Record<string, any>>;
+
+/**
+ * Scan profile presets for AgentValidator.
+ *
+ * Port of Python agentseal/profiles.py.
+ */
+interface ProfileConfig {
+    description: string;
+    adaptive?: boolean;
+    semantic?: boolean;
+    mcp?: boolean;
+    rag?: boolean;
+    multimodal?: boolean;
+    genome?: boolean;
+    useCanaryOnly?: boolean;
+    concurrency?: number;
+    timeout?: number;
+    output?: string;
+    minScore?: number;
+}
+declare const PROFILES: Record<string, ProfileConfig>;
+/** Return a profile by name, or throw with valid options. */
+declare function resolveProfile(name: string): ProfileConfig;
+/**
+ * Apply profile settings to an options object without overriding explicit user values.
+ * Boolean flags are only set when the current value is falsy.
+ * Optional fields are only set when the current value is undefined/null.
+ */
+declare function applyProfile(opts: Record<string, any>, profile: ProfileConfig): void;
+/** Return a formatted table of available profiles. */
+declare function listProfiles(): string;
+
 /** Encode attack text in base64 and wrap with decode instructions. */
 declare function base64Wrap(text: string): string;
 
@@ -332,4 +385,652 @@ declare function generateRemediation(report: ScanReport): RemediationReport;
 /** Compare two scan reports and return a diff summary. */
 declare function compareReports(baseline: ScanReport, current: ScanReport): CompareResult;
 
-export { type AffectedProbe, AgentSealError, AgentValidator, BOUNDARY_CATEGORIES, BOUNDARY_WEIGHT, COMMON_WORDS, CONSISTENCY_WEIGHT, type ChatFn, type CompareResult, DATA_EXTRACTION_WEIGHT, type DefenseProfile, EXTRACTION_WEIGHT, type EmbedFn, INJECTION_WEIGHT, type Probe, type ProbeResult, ProbeTimeoutError, type ProgressFn, ProviderError, REFUSAL_PHRASES, type RemediationItem, type RemediationReport, SEMANTIC_HIGH_THRESHOLD, SEMANTIC_MODERATE_THRESHOLD, type ScanReport, type ScoreBreakdown, Severity, TRANSFORMS, TrustLevel, ValidationError, type ValidatorOptions, Verdict, base64Wrap, buildExtractionProbes, buildInjectionProbes, caseScramble, compareReports, computeScores, computeSemanticSimilarity, detectCanary, detectExtraction, detectExtractionWithSemantic, extractUniquePhrases, fingerprintDefense, fromAnthropic, fromEndpoint, fromLangChain, fromOllama, fromOpenAI, fromVercelAI, fuseVerdicts, generateCanary, generateMutations, generateRemediation, isRefusal, leetspeak, prefixPadding, reverseEmbed, rot13Wrap, trustLevelFromScore, unicodeHomoglyphs, verdictScore, zeroWidthInject };
+/**
+ * Text deobfuscation transforms for skill file content.
+ *
+ * Applied BEFORE regex pattern matching to make obfuscated payloads
+ * visible to existing detection patterns. Zero dependencies.
+ *
+ * Port of Python agentseal/deobfuscate.py — same transforms, same order.
+ */
+/** Remove zero-width characters: U+200B, U+200C, U+200D, U+FEFF, U+00AD, U+2060. */
+declare function stripZeroWidth(text: string): string;
+/** Remove Unicode Tag Characters (U+E0001–U+E007F) used in ASCII smuggling. */
+declare function stripTagChars(text: string): string;
+/** Remove Variation Selectors (U+FE00–FE0F, U+E0100–E01EF). */
+declare function stripVariationSelectors(text: string): string;
+/** Remove BiDi control characters that can hide text direction. */
+declare function stripBidiControls(text: string): string;
+/** Remove HTML comments that may contain hidden instructions. */
+declare function stripHtmlComments(text: string): string;
+/** Check if text contains any invisible/obfuscation characters. */
+declare function hasInvisibleChars(text: string): boolean;
+/** Apply NFKC unicode normalization (homoglyphs → ASCII). */
+declare function normalizeUnicode(text: string): string;
+/**
+ * Find and decode inline base64 strings.
+ * Only decodes standalone tokens >= 8 chars that produce valid printable UTF-8.
+ */
+declare function decodeBase64Blocks(text: string): string;
+/**
+ * Convert common escape sequences to actual characters.
+ * Handles: \xHH, \uHHHH, \n, \t, \r, \\.
+ * Does NOT eval() anything.
+ */
+declare function unescapeSequences(text: string): string;
+/**
+ * Join adjacent string literal concatenations.
+ * "abc" + "def" → "abcdef"
+ * 'abc' + 'def' → 'abcdef'
+ * Iterates until no more concatenations remain (handles chains).
+ */
+declare function expandStringConcat(text: string): string;
+/**
+ * Apply all deobfuscation transforms to text.
+ *
+ * Returns cleaned text for regex pattern matching.
+ * Transforms applied in order (same as Python):
+ * 1. stripZeroWidth
+ * 2. stripTagChars
+ * 3. stripVariationSelectors
+ * 4. stripBidiControls
+ * 5. stripHtmlComments
+ * 6. normalizeUnicode (NFKC)
+ * 7. decodeBase64Blocks
+ * 8. unescapeSequences
+ * 9. expandStringConcat
+ */
+declare function deobfuscate(text: string): string;
+
+/**
+ * Data models for the guard command — machine-level security scanning.
+ *
+ * Port of Python agentseal/guard_models.py — same structure, TypeScript interfaces.
+ */
+declare const GuardVerdict: {
+    readonly SAFE: "safe";
+    readonly WARNING: "warning";
+    readonly DANGER: "danger";
+    readonly ERROR: "error";
+};
+type GuardVerdict = (typeof GuardVerdict)[keyof typeof GuardVerdict];
+declare const SEVERITY_ORDER: Record<string, number>;
+interface SkillFinding {
+    code: string;
+    title: string;
+    description: string;
+    severity: string;
+    evidence: string;
+    remediation: string;
+}
+interface SkillResult {
+    name: string;
+    path: string;
+    verdict: GuardVerdict;
+    findings: SkillFinding[];
+    blocklist_match: boolean;
+    sha256: string;
+}
+/** Return the highest-severity finding from a SkillResult, or undefined. */
+declare function topSkillFinding(result: SkillResult): SkillFinding | undefined;
+interface MCPFinding {
+    code: string;
+    title: string;
+    description: string;
+    severity: string;
+    remediation: string;
+}
+interface MCPServerResult {
+    name: string;
+    command: string;
+    source_file: string;
+    verdict: GuardVerdict;
+    findings: MCPFinding[];
+}
+/** Return the highest-severity finding from an MCPServerResult, or undefined. */
+declare function topMCPFinding(result: MCPServerResult): MCPFinding | undefined;
+interface AgentConfigResult {
+    name: string;
+    config_path: string;
+    agent_type: string;
+    mcp_servers: number;
+    skills_count: number;
+    status: string;
+}
+interface MCPRuntimeFinding {
+    code: string;
+    title: string;
+    description: string;
+    severity: string;
+    evidence: string;
+    remediation: string;
+    tool_name: string;
+    server_name: string;
+}
+interface MCPRuntimeResult {
+    server_name: string;
+    tools_found: number;
+    findings: MCPRuntimeFinding[];
+    verdict: GuardVerdict;
+    connection_status: string;
+}
+interface ToxicFlowResult {
+    risk_level: string;
+    risk_type: string;
+    title: string;
+    description: string;
+    servers_involved: string[];
+    remediation: string;
+    tools_involved: string[];
+    labels_involved: string[];
+}
+interface BaselineChangeResult {
+    server_name: string;
+    agent_type: string;
+    change_type: string;
+    detail: string;
+}
+interface GuardReport {
+    timestamp: string;
+    duration_seconds: number;
+    agents_found: AgentConfigResult[];
+    skill_results: SkillResult[];
+    mcp_results: MCPServerResult[];
+    mcp_runtime_results: MCPRuntimeResult[];
+    toxic_flows: ToxicFlowResult[];
+    baseline_changes: BaselineChangeResult[];
+    llm_tokens_used: number;
+}
+declare function totalDangers(report: GuardReport): number;
+declare function totalWarnings(report: GuardReport): number;
+declare function totalSafe(report: GuardReport): number;
+declare function hasCritical(report: GuardReport): boolean;
+/** Collect all remediation actions, sorted by severity. */
+declare function allActions(report: GuardReport): string[];
+
+/**
+ * Skill threat detection — layered analysis for skill/rules files.
+ *
+ * Layer 1: Static pattern matching (compiled regex, ~1ms per skill)
+ * Layer 2: Semantic similarity against known danger concepts (optional)
+ *
+ * Port of Python agentseal/detection/skill_detector.py — same patterns, same order.
+ */
+
+declare const DANGER_CONCEPTS: string[];
+declare class SkillScanner {
+    /** Layer 1: Fast static pattern matching against known threat patterns. */
+    scanPatterns(content: string): SkillFinding[];
+    /**
+     * Layer 2: Semantic similarity against known danger concepts.
+     *
+     * Requires an embedding function. Returns empty array if not provided.
+     * Compares content chunks against DANGER_CONCEPTS with similarity thresholds.
+     */
+    scanSemantic(content: string, embedFn?: (texts: string[]) => Promise<number[][]>): Promise<SkillFinding[]>;
+}
+
+/**
+ * Malicious skill blocklist client.
+ *
+ * Maintains a local cache of known-malicious skill hashes.
+ * Auto-updates from agentseal.org on each run (with 1-hour cache TTL).
+ * Works fully offline — falls back to cached or empty blocklist.
+ *
+ * Port of Python agentseal/blocklist.py — same logic.
+ */
+declare class Blocklist {
+    static readonly REMOTE_URL = "https://agentseal.org/api/v1/blocklist/skills.json";
+    static readonly CACHE_TTL = 3600;
+    private _hashes;
+    private _loaded;
+    private _cacheDir;
+    private _cachePath;
+    constructor(cacheDir?: string);
+    /** Override cache dir (useful for testing). */
+    setCacheDir(dir: string): void;
+    private _load;
+    private _loadFromFile;
+    private _tryRemoteFetch;
+    /** Async remote fetch — call this once at startup if you want remote blocklist. */
+    loadAsync(): Promise<void>;
+    /** Check if a SHA256 hash is in the blocklist. */
+    isBlocked(sha256: string): boolean;
+    /** Number of hashes in the blocklist. */
+    get size(): number;
+    /** Manually add hashes (for testing or seed data). */
+    addHashes(hashes: string[]): void;
+}
+/** Compute SHA256 hash of content. */
+declare function sha256(content: string): string;
+
+/**
+ * Toxic flow detection — static analysis of MCP server capability combinations.
+ *
+ * Classifies MCP servers by capability labels and detects dangerous
+ * combinations that could enable data exfiltration, remote code execution,
+ * or data destruction.
+ *
+ * Port of Python agentseal/toxic_flows.py — static analysis only.
+ */
+
+declare const LABEL_PUBLIC_SINK = "public_sink";
+declare const LABEL_DESTRUCTIVE = "destructive";
+declare const LABEL_UNTRUSTED = "untrusted_content";
+declare const LABEL_PRIVATE = "private_data";
+declare const KNOWN_SERVER_LABELS: Record<string, Set<string>>;
+declare function classifyServer(server: Record<string, any>): Set<string>;
+/**
+ * Analyze MCP servers for dangerous capability combinations.
+ * Requires at least 2 servers for cross-server flow detection.
+ */
+declare function analyzeToxicFlows(servers: Array<Record<string, any>>): ToxicFlowResult[];
+
+/**
+ * Rug pull detection via baseline fingerprinting.
+ *
+ * On first scan, fingerprints MCP server configurations. On subsequent scans,
+ * detects changes and alerts the user.
+ *
+ * Storage: ~/.agentseal/baselines/{agent_type}/{server_name}.json
+ *
+ * Port of Python agentseal/baselines.py.
+ */
+interface BaselineEntry {
+    server_name: string;
+    agent_type: string;
+    config_hash: string;
+    binary_hash: string | null;
+    binary_path: string | null;
+    command: string;
+    args: string[];
+    first_seen: string;
+    last_verified: string;
+    tool_signatures_hash?: string | null;
+    tool_count?: number | null;
+    tools_detail?: Array<{
+        name: string;
+        hash: string;
+    }> | null;
+}
+interface BaselineChange {
+    server_name: string;
+    agent_type: string;
+    change_type: string;
+    old_value?: string | null;
+    new_value?: string | null;
+    detail: string;
+}
+declare class BaselineStore {
+    private readonly _dir;
+    constructor(baselinesDir?: string);
+    private _entryPath;
+    /** Load a stored baseline entry. Returns null if not found. */
+    load(agentType: string, serverName: string): BaselineEntry | null;
+    /** Save a baseline entry to disk. */
+    save(entry: BaselineEntry): void;
+    /** Check a single MCP server against its stored baseline. */
+    checkServer(server: Record<string, any>): BaselineChange | null;
+    /** Check all servers. Returns list of changes (empty = no changes). */
+    checkAll(servers: Array<Record<string, any>>, includeNew?: boolean): BaselineChange[];
+    /** Remove all baselines. Returns count of entries removed. */
+    reset(): number;
+    /** List all stored baseline entries. */
+    listEntries(): BaselineEntry[];
+}
+
+/**
+ * MCP Config Checker — static analysis of MCP server configurations.
+ *
+ * Reads JSON config dicts and flags dangerous permissions, exposed credentials,
+ * and supply chain risks. Does NOT connect to MCP servers.
+ *
+ * Port of Python agentseal/mcp_checker.py — same checks, same codes.
+ */
+
+declare function shannonEntropy(s: string): number;
+declare function verdictFromFindings(findings: MCPFinding[]): GuardVerdict;
+declare class MCPConfigChecker {
+    /** Check a single MCP server config dict for security issues. */
+    check(server: Record<string, any>): MCPServerResult;
+    /** Check multiple MCP server configs. */
+    checkAll(servers: Array<Record<string, any>>): MCPServerResult[];
+    private _checkSensitivePaths;
+    private _checkEnvCredentials;
+    private _checkBroadAccess;
+    private _checkInsecureUrls;
+    private _checkHttpServer;
+    private _checkSupplyChain;
+    private _checkCommandInjection;
+    private _checkMissingAuth;
+    private _checkKnownCVEs;
+    private _checkHighEntropySecrets;
+}
+
+/**
+ * Guard — one-command machine security scan.
+ *
+ * Chains machine discovery, skill scanning, blocklist, and deobfuscation
+ * into a single zero-config experience.
+ *
+ * Port of Python agentseal/guard.py + agentseal/skill_scanner.py.
+ */
+
+type GuardProgressFn = (phase: string, detail: string) => void;
+interface GuardOptions {
+    /** Enable semantic analysis (requires embedFn). Default: false */
+    semantic?: boolean;
+    /** Verbose output. Default: false */
+    verbose?: boolean;
+    /** Progress callback. */
+    onProgress?: GuardProgressFn;
+    /** Embedding function for semantic analysis. */
+    embedFn?: (texts: string[]) => Promise<number[][]>;
+    /** Scan a specific directory instead of the whole machine. */
+    scanPath?: string;
+}
+/** Extract a human-readable name from a skill file path. */
+declare function extractSkillName(filePath: string): string;
+/** Determine verdict from findings. Worst severity wins. */
+declare function computeVerdict(findings: SkillFinding[]): GuardVerdict;
+/** Scan a single skill file through all detection layers. */
+declare function scanSkillFile(filePath: string, scanner: SkillScanner, blocklist: Blocklist): SkillResult;
+declare class Guard {
+    private readonly _options;
+    constructor(options?: GuardOptions);
+    /** Execute full guard scan. Returns a GuardReport with all findings. */
+    run(): GuardReport;
+}
+
+/**
+ * Machine-level agent discovery — finds ALL AI agents, MCP servers, and skills
+ * installed on the user's machine by checking well-known config paths.
+ *
+ * Port of Python agentseal/machine_discovery.py — same locations, same logic.
+ */
+
+/** Project-level MCP config definitions. [relPath, mcpKey, format] */
+declare const PROJECT_MCP_CONFIGS: Array<[string, string, string | null]>;
+/** Project-level skill files. */
+declare const PROJECT_SKILL_FILES: string[];
+/** Project-level skill directories. */
+declare const PROJECT_SKILL_DIRS: string[];
+interface AgentDef {
+    name: string;
+    agent_type: string;
+    paths: Record<string, string | null>;
+    mcp_key: string | null;
+    format?: string;
+}
+declare function getWellKnownConfigs(): AgentDef[];
+/** Strip // and /* * / comments from JSONC. Preserves URLs inside strings. */
+declare function stripJsonComments(text: string): string;
+interface MCPServerConfig {
+    name: string;
+    source_file: string;
+    agent_type: string;
+    [key: string]: unknown;
+}
+interface DiscoveryResult {
+    agents: AgentConfigResult[];
+    mcpServers: MCPServerConfig[];
+    skillPaths: string[];
+}
+/**
+ * Discover all AI agents, MCP servers, and skills on this machine.
+ * Scans well-known config paths + CWD.
+ */
+declare function scanMachine(): DiscoveryResult;
+/**
+ * Scan a specific project directory for MCP configs and skill files.
+ * Unlike scanMachine(), this only looks within the given directory.
+ */
+declare function scanDirectory(directory: string): DiscoveryResult;
+
+/**
+ * Fix engine — skill quarantine + report loading.
+ *
+ * Provides core logic for the `agentseal fix` command:
+ *   - Quarantine dangerous skills (move to ~/.agentseal/quarantine/)
+ *   - Restore quarantined skills
+ *   - Load/save guard and scan reports
+ *   - Extract fixable skills from guard reports
+ *
+ * Port of Python agentseal/fix.py.
+ */
+declare const QUARANTINE_DIR: string;
+declare const REPORTS_DIR: string;
+declare const BACKUPS_DIR: string;
+interface QuarantineEntry {
+    original_path: string;
+    quarantine_path: string;
+    reason: string;
+    timestamp: string;
+    skill_name: string;
+}
+interface FixResult {
+    action: string;
+    target: string;
+    detail: string;
+    before: string | null;
+    after: string | null;
+}
+/**
+ * Move a dangerous skill to quarantine.
+ *
+ * Preserves relative directory structure under the quarantine dir.
+ * Handles duplicate filenames by adding _1, _2, etc. suffixes.
+ */
+declare function quarantineSkill(skillPath: string, reason?: string, quarantineDir?: string): QuarantineEntry;
+/**
+ * Restore a quarantined skill to its original location.
+ *
+ * @throws Error if skill not in quarantine, original path occupied, or file missing.
+ */
+declare function restoreSkill(skillName: string, quarantineDir?: string): string;
+/** List all quarantined skills from manifest. */
+declare function listQuarantine(quarantineDir?: string): QuarantineEntry[];
+/** Load guard report from file or latest from reportsDir. */
+declare function loadGuardReport(path?: string, reportsDir?: string): Record<string, any>;
+/** Load scan report from file or latest from reportsDir. */
+declare function loadScanReport(path?: string, reportsDir?: string): Record<string, any>;
+/** Save report to reportsDir/{type}-latest.json. Creates dir if needed. */
+declare function saveReport(reportDict: Record<string, any>, reportType: string, reportsDir?: string): string;
+/** Extract skills with DANGER verdict from guard report. */
+declare function getFixableSkills(guardReport: Record<string, any>): Array<Record<string, any>>;
+
+/**
+ * Attack chain detection from scan results.
+ *
+ * Analyzes existing ProbeResult data to identify complete attack paths.
+ * Does NOT run new probes.
+ *
+ * Port of Python agentseal/chains.py.
+ */
+
+interface ChainStep {
+    step_number: number;
+    probe_id: string;
+    category: string;
+    technique: string;
+    verdict: string;
+    summary: string;
+}
+interface AttackChain {
+    chain_type: string;
+    severity: string;
+    title: string;
+    description: string;
+    steps: ChainStep[];
+    remediation: string;
+}
+/** Analyze probe results to identify complete attack chains. */
+declare function detectChains(report: ScanReport): AttackChain[];
+
+/**
+ * LLM Judge — optional AI-powered analysis layer for skill scanning.
+ *
+ * Sends skill file content to an LLM for deep security analysis.
+ * Users bring their own API key. Supports OpenAI, Anthropic, Ollama, and
+ * OpenRouter; anything OpenAI-compatible works too.
+ *
+ * Port of Python agentseal/llm_judge.py.
+ */
+declare const MAX_CONTENT_BYTES: number;
+interface LLMJudgeFinding {
+    title: string;
+    severity?: string;
+    evidence?: string;
+    reasoning?: string;
+}
+interface LLMJudgeResult {
+    verdict: string;
+    confidence: number;
+    findings: LLMJudgeFinding[];
+    model: string;
+    tokens_used: number;
+    error?: string | null;
+}
+declare const SYSTEM_PROMPT: string;
+declare function detectProvider(model: string): string;
+declare function stripModelPrefix(model: string, provider: string): string;
+declare function parseResponse(raw: string, model: string, tokens: number): LLMJudgeResult;
+/** Truncate content to MAX_CONTENT_BYTES. */
+declare function truncateContent(content: string): string;
+interface LLMJudgeOptions {
+    model: string;
+    apiKey?: string;
+    baseUrl?: string;
+    timeout?: number;
+}
+/**
+ * Send skill content to an LLM for security analysis.
+ *
+ * Supported model formats:
+ *   "gpt-4o", "gpt-4o-mini"         -> OpenAI  (OPENAI_API_KEY)
+ *   "claude-sonnet-4-5-20250929"     -> Anthropic (ANTHROPIC_API_KEY)
+ *   "ollama/llama3.1:8b"            -> Ollama local
+ *   "openrouter/..."                -> OpenRouter
+ */
+declare class LLMJudge {
+    readonly model: string;
+    readonly provider: string;
+    readonly apiKey: string | undefined;
+    readonly baseUrl: string | undefined;
+    readonly timeout: number;
+    constructor(options: LLMJudgeOptions);
+    /** Analyse a single skill file. Never throws. */
+    analyzeSkill(content: string, filename: string): Promise<LLMJudgeResult>;
+    /** Analyse multiple (content, filename) pairs with concurrency control. */
+    analyzeBatch(files: Array<[string, string]>, concurrency?: number): Promise<LLMJudgeResult[]>;
+    private _callOpenAICompat;
+    private _callAnthropic;
+}
+
+/**
+ * Desktop notifications for AgentSeal Shield.
+ *
+ * Uses OS built-in notification mechanisms — no additional dependencies.
+ * macOS: osascript, Linux: notify-send, Fallback: terminal bell + stderr.
+ *
+ * Port of Python agentseal/notify.py.
+ */
+declare class Notifier {
+    private _enabled;
+    private _minInterval;
+    private _lastNotifyTime;
+    private _platform;
+    constructor(enabled?: boolean, minInterval?: number);
+    get enabled(): boolean;
+    /** Send a desktop notification. Returns true if sent. Respects throttle interval. */
+    notify(title: string, message: string, urgent?: boolean): boolean;
+    /** Send a threat notification with standard formatting. */
+    notifyThreat(itemName: string, itemType: string, severity: string, detail: string): boolean;
+    private _dispatch;
+    private _notifyMacOS;
+    private _notifyLinux;
+    private _notifyFallback;
+}
+
+/**
+ * Shield — continuous filesystem monitoring for AI agent security.
+ *
+ * Watches skill directories, MCP config files, and agent config dirs.
+ * When a file changes, triggers an incremental scan and optionally sends
+ * desktop notifications.
+ *
+ * Uses Node.js built-in fs.watch (recursive on macOS/Windows).
+ *
+ * Port of Python agentseal/shield.py.
+ */
+/** Callback: (eventType, path, resultSummary) */
+type ShieldCallback = (eventType: string, path: string, summary: string) => void;
+interface ShieldOptions {
+    /** Enable semantic analysis. Default: false */
+    semantic?: boolean;
+    /** Enable desktop notifications. Default: true */
+    notify?: boolean;
+    /** Debounce seconds for filesystem events. Default: 2.0 */
+    debounceSeconds?: number;
+    /** Callback for shield events. */
+    onEvent?: ShieldCallback;
+}
+/**
+ * Per-path debouncing for filesystem events.
+ * Accumulates events and fires only after a quiet period.
+ */
+declare class DebouncedHandler {
+    private _onChange;
+    private _debounceMs;
+    private _timers;
+    constructor(onChange: (filePath: string) => void, debounceMs?: number);
+    /** Handle a filesystem event. Skips directories and temp files. */
+    handleEvent(filePath: string, isDirectory?: boolean): void;
+    /** Cancel all pending timers. */
+    cancelAll(): void;
+    /** Number of pending timers (for testing). */
+    get pendingCount(): number;
+}
+/** Classify a changed file as 'skill', 'mcp_config', or 'unknown'. */
+declare function classifyPath(filePath: string): string;
+/** Collect all paths that shield should monitor. */
+declare function collectWatchPaths(homeOverride?: string): {
+    dirs: string[];
+    files: string[];
+};
+declare class Shield {
+    private _onEvent;
+    private _notifier;
+    private _scanner;
+    private _mcpChecker;
+    private _blocklist;
+    private _baselineStore;
+    private _debounceMs;
+    private _watchers;
+    private _handler;
+    private _running;
+    private _scanCount;
+    private _threatCount;
+    constructor(options?: ShieldOptions);
+    get scanCount(): number;
+    get threatCount(): number;
+    get running(): boolean;
+    /** Handle a single file change event. */
+    handleChange(filePath: string): void;
+    private _scanSkill;
+    private _scanMcpConfig;
+    /**
+     * Start watching. Returns { dirsWatched, filesWatched }.
+     *
+     * Uses Node.js fs.watch with recursive option (macOS/Windows).
+     * Does NOT block — call stop() to clean up.
+     */
+    start(homeOverride?: string): {
+        dirsWatched: number;
+        filesWatched: number;
+    };
+    /** Stop the filesystem watchers. */
+    stop(): void;
+}
+
+export { type AffectedProbe, type AgentConfigResult, AgentSealError, AgentValidator, type AttackChain, BACKUPS_DIR, BOUNDARY_CATEGORIES, BOUNDARY_WEIGHT, type BaselineChange, type BaselineChangeResult, type BaselineEntry, BaselineStore, Blocklist, COMMON_WORDS, CONSISTENCY_WEIGHT, type ChainStep, type ChatFn, type CompareResult, DANGER_CONCEPTS, DATA_EXTRACTION_WEIGHT, DebouncedHandler, type DefenseProfile, type DiscoveryResult, EXTRACTION_WEIGHT, type EmbedFn, type FixResult, Guard, type GuardOptions, type GuardProgressFn, type GuardReport, GuardVerdict, INJECTION_WEIGHT, KNOWN_SERVER_LABELS, LABEL_DESTRUCTIVE, LABEL_PRIVATE, LABEL_PUBLIC_SINK, LABEL_UNTRUSTED, LLMJudge, type LLMJudgeFinding, type LLMJudgeOptions, type LLMJudgeResult, MAX_CONTENT_BYTES, MCPConfigChecker, type MCPFinding, type MCPRuntimeFinding, type MCPRuntimeResult, type MCPServerResult, Notifier, PROFILES, PROJECT_MCP_CONFIGS, PROJECT_SKILL_DIRS, PROJECT_SKILL_FILES, type Probe, type ProbeResult, ProbeTimeoutError, type ProfileConfig, type ProgressFn, ProviderError, QUARANTINE_DIR, type QuarantineEntry, REFUSAL_PHRASES, REPORTS_DIR, type RemediationItem, type RemediationReport, SEMANTIC_HIGH_THRESHOLD, SEMANTIC_MODERATE_THRESHOLD, SEVERITY_ORDER, SYSTEM_PROMPT, type ScanReport, type ScoreBreakdown, Severity, Shield, type ShieldCallback, type ShieldOptions, type SkillFinding, type SkillResult, SkillScanner, TRANSFORMS, type ToxicFlowResult, TrustLevel, ValidationError, type ValidatorOptions, Verdict, allActions, analyzeToxicFlows, applyProfile, base64Wrap, buildExtractionProbes, buildInjectionProbes, buildProbe, caseScramble, classifyPath, classifyServer, collectWatchPaths, compareReports, computeScores, computeSemanticSimilarity, computeVerdict, decodeBase64Blocks, deobfuscate, detectCanary, detectChains, detectExtraction, detectExtractionWithSemantic, detectProvider, expandStringConcat, extractSkillName, extractUniquePhrases, fingerprintDefense, fromAnthropic, fromEndpoint, fromLangChain, fromOllama, fromOpenAI, fromVercelAI, fuseVerdicts, generateCanary, generateMutations, generateRemediation, getFixableSkills, getWellKnownConfigs, hasCritical, hasInvisibleChars, isRefusal, leetspeak, listProfiles, listQuarantine, loadAllCustomProbes, loadCustomProbes, loadGuardReport, loadScanReport, normalizeUnicode, parseProbeFile, parseResponse, prefixPadding, quarantineSkill, resolveProfile, restoreSkill, reverseEmbed, rot13Wrap, saveReport, scanDirectory, scanMachine, scanSkillFile, sha256, shannonEntropy, stripBidiControls, stripHtmlComments, stripJsonComments, stripModelPrefix, stripTagChars, stripVariationSelectors, stripZeroWidth, topMCPFinding, topSkillFinding, totalDangers, totalSafe, totalWarnings, truncateContent, trustLevelFromScore, unescapeSequences, unicodeHomoglyphs, validateProbe, verdictFromFindings, verdictScore, zeroWidthInject };