shroud-privacy 2.2.11 → 2.2.12

package/README.md

@@ -88,9 +88,10 @@ Shroud does not guarantee compliance — regex-based detection has limitations (
 ```bash
 openclaw --version    # ensure 2026.3.22+
 openclaw plugins install shroud-privacy
+openclaw gateway restart
 ```
 
-Configure in `~/.openclaw/openclaw.json` under `plugins.entries."shroud-privacy".config`. No OpenClaw file modifications needed — Shroud uses runtime interception only.
+That's it — Shroud is automatically enabled on install. All 100+ detectors are active with safe defaults, no configuration required. To customise, see [Configure](#configure).
 
 ### Any agent (via APP)
 
@@ -166,13 +167,13 @@ openclaw gateway restart
 
 ## Configure
 
-Edit `~/.openclaw/openclaw.json` under `plugins.entries."shroud-privacy".config`:
+Shroud works out of the box with zero configuration. `openclaw plugins install` sets `enabled: true` automatically. To customise, edit `~/.openclaw/openclaw.json` under `plugins.entries."shroud-privacy".config`:
 
 ```jsonc
 "shroud-privacy": {
-  "enabled": true,
+  "enabled": true,                       // set automatically by plugins install
   "config": {
-    "auditEnabled": true           // audit log on — see what Shroud is doing
+    "auditEnabled": true                 // audit log on — see what Shroud is doing
     // "minConfidence": 0.0              // catch everything (default)
     // "secretKey": ""                   // auto-generated if empty
     // "persistentSalt": ""              // set for cross-session consistency

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "shroud-privacy",
   "name": "Shroud",
-  "version": "2.2.11",
+  "version": "2.2.12",
   "description": "Privacy obfuscation with deterministic fake values and deobfuscation — PII never reaches the LLM, tool calls still work",
   "configSchema": {
     "type": "object",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shroud-privacy",
-  "version": "2.2.11",
+  "version": "2.2.12",
   "description": "Privacy and infrastructure protection for AI agents — detects sensitive data (PII, network topology, credentials, OT/SCADA) and replaces with deterministic fakes before anything reaches the LLM.",
   "type": "module",
   "main": "dist/index.js",

package/dist/agent-session.d.ts

@@ -1,259 +0,0 @@
-/**
- * Agent session tracking — maps LLM API calls to local agent identities.
- *
- * Each agent has a unique identity derived from its system prompt, plugin set,
- * and model. This module tracks which agent is making each LLM call, enabling:
- * - Per-agent WAF rules (different injection policies per agent)
- * - Per-agent behavioural baselines (Track 3)
- * - Per-agent canary attribution (Track 2)
- * - Multi-agent session correlation
- */
-/** A logged LLM API call. */
-export interface LlmCallRecord {
-    timestamp: number;
-    agentLabel: string;
-    url: string;
-    model: string;
-    inputTokens: number;
-    outputTokens: number;
-    cacheReadTokens: number;
-    cacheWriteTokens: number;
-    cacheHitPct: number;
-    responseTimeMs: number;
-    channel: string;
-    securityEvents: number;
-    /** Why the call was made (slack message, heartbeat, cron, tool call, etc.) */
-    reason: string;
-}
-/** Agent role classification derived from name, channel, and behaviour. */
-export interface AgentClassification {
-    /** Primary role category. */
-    role: string;
-    /** Confidence percentage (0-100). */
-    confidencePct: number;
-    /** Confidence tier for display. */
-    confidence: "high" | "medium" | "low";
-    /** Colour code for dashboard rendering. */
-    colour: string;
-    /** Keywords that triggered the classification. */
-    signals: string[];
-}
-/** Agent health and behavioural compliance status. */
-export interface AgentHealth {
-    /** Overall health: "healthy", "warning", "critical". */
-    status: "healthy" | "warning" | "critical";
-    /** Health colour for dashboard. */
-    colour: string;
-    /** Is the agent behaving according to its classification? */
-    compliant: boolean;
-    /** Compliance detail messages. */
-    issues: string[];
-    /** Last active relative indicator. */
-    lastActiveAgo: string;
-    /** Security event rate per 100 calls. */
-    eventRate: number;
-}
-/** Represents a tracked agent session. */
-export interface AgentSession {
-    /** Stable identity hash: SHA256(systemPrompt + pluginList + modelId). */
-    agentBuildId: string;
-    /** Human-readable label extracted from system prompt (first 60 chars). */
-    agentLabel: string;
-    /** Session-scoped unique ID. */
-    sessionId: string;
-    /** When this session was first seen. */
-    startedAt: number;
-    /** Total LLM API calls made by this agent session. */
-    llmCallCount: number;
-    /** Total security events attributed to this agent. */
-    securityEventCount: number;
-    /** Last LLM call timestamp. */
-    lastCallAt: number;
-    /** LLM model ID detected from API calls (e.g. "claude-3-opus", "gpt-4"). */
-    detectedModel: string;
-    /** Channel source if detected (e.g. "slack:C00000001", "whatsapp:+353..."). */
-    channelSource: string;
-    /** Inferred role classification. */
-    classification: AgentClassification;
-    /** Tool names available to the agent (from body.tools). */
-    toolInventory: string[];
-    /** SOUL.md extract — agent's core identity/instructions from early messages. */
-    soulExtract: string;
-    /** Per-agent LLM cache stats. */
-    cache: AgentCacheStats;
-    /** Active channels this agent has been seen on. */
-    channels: string[];
-    /** Heartbeat tracking. */
-    heartbeat: AgentHeartbeat;
-}
-/** Per-agent heartbeat tracking. */
-export interface AgentHeartbeat {
-    /** Whether heartbeat has been detected for this agent. */
-    enabled: boolean;
-    /** Timestamps of recent heartbeats (last 10). */
-    recent: number[];
-    /** Average interval between heartbeats (ms). -1 if not enough data. */
-    avgIntervalMs: number;
-    /** Last heartbeat timestamp. */
-    lastAt: number;
-    /** Status: "alive", "stale" (2x interval missed), "dead" (5x missed). */
-    status: "alive" | "stale" | "dead" | "unknown";
-    /** Last heartbeat response (HEARTBEAT_OK or alert text). */
-    lastResponse: string;
-}
-/** Per-agent LLM cache tracking for anomaly detection. */
-export interface AgentCacheStats {
-    totalInputTokens: number;
-    totalOutputTokens: number;
-    totalCacheRead: number;
-    totalCacheWrite: number;
-    /** Running average cache hit ratio (0-1). */
-    avgHitRatio: number;
-    /** Baseline hit ratio (from first N calls). -1 if not established. */
-    baselineHitRatio: number;
-    /** Number of calls contributing to the baseline. */
-    baselineSamples: number;
-    /** Number of calls with cache data. */
-    callsWithCache: number;
-}
-/**
- * Tracks agent sessions and maps LLM calls to agent identities.
- * One instance shared via globalThis across all plugin loads.
- */
-export declare class AgentSessionTracker {
-    /** Active sessions keyed by agent label (the stable identity). */
-    private _sessions;
-    /** Current active agent label. */
-    private _currentLabel;
-    /** LLM call log (ring buffer, last 200 calls). */
-    private _callLog;
-    /** Timestamp when the current LLM call started (for response time). */
-    private _callStartTime;
-    /**
-     * Register or update an agent session from system prompt content.
-     *
-     * Identity strategy: the extracted LABEL is the primary key, not the
-     * prompt skeleton hash. System prompts contain too much dynamic content
-     * (conversation context, RAG, tool results) to produce stable hashes.
-     * The label — extracted from "- Name: X", "You are X", etc. — is the
-     * stable identity that humans recognise.
-     *
-     * The buildId is still computed for fingerprinting but is NOT used as
-     * the session key.
-     */
-    registerAgent(systemPrompt: string, pluginList?: string[], modelId?: string): AgentSession;
-    /** Update detected model from LLM API request body. */
-    updateModel(model: string): void;
-    /** Update channel source (e.g. "slack:C00000001"). */
-    updateChannel(source: string): void;
-    /**
-     * Update per-agent cache stats from an LLM response.
-     * Returns anomaly alerts if cache behaviour deviates from baseline.
-     */
-    updateCache(usage: {
-        inputTokens: number;
-        outputTokens: number;
-        cacheReadTokens: number;
-        cacheWriteTokens: number;
-    }): {
-        alert: string;
-        severity: "medium" | "high";
-    } | null;
-    /** Record a heartbeat for the current agent. Returns alert if missed. */
-    recordHeartbeat(response?: string): {
-        alert: string;
-        severity: "medium" | "high";
-    } | null;
-    /** Check all agents for missed heartbeats. Call periodically. */
-    checkHeartbeatHealth(): Array<{
-        agentLabel: string;
-        status: string;
-        alert: string;
-    }>;
-    /** Detect and record the channel from prompt metadata. */
-    updateChannelFromPrompt(prompt: string): string | null;
-    /** Update tool inventory from body.tools array. Only sets once (first call). */
-    updateTools(tools: string[]): void;
-    /** Update SOUL extract from early messages. Only sets once. */
-    updateSoul(soul: string): void;
-    /** Record an LLM API call for the current agent. */
-    recordLlmCall(): AgentSession | null;
-    /** Record a security event for the current agent. */
-    recordSecurityEvent(count?: number): void;
-    /** Get the current active agent session. */
-    getCurrentSession(): AgentSession | null;
-    /** Get the current agent build ID. */
-    getCurrentBuildId(): string;
-    /** Get all tracked agent sessions. */
-    getAllSessions(): AgentSession[];
-    /** Get session by build ID. */
-    getSession(buildId: string): AgentSession | null;
-    /** Get session by label (primary key). */
-    getSessionByLabel(label: string): AgentSession | null;
-    /** Mark the start of an LLM call (for response time tracking). */
-    markCallStart(): void;
-    /** Log a completed LLM call with full details. */
-    logCall(details: {
-        url: string;
-        model: string;
-        inputTokens: number;
-        outputTokens: number;
-        cacheReadTokens: number;
-        cacheWriteTokens: number;
-        channel: string;
-        securityEvents: number;
-        reason: string;
-    }): void;
-    /** Get the LLM call log. */
-    getCallLog(): readonly LlmCallRecord[];
-    /** Reset all session tracking. */
-    reset(): void;
-}
-/**
- * Compute a stable agent build ID.
- *
- * Uses a "skeleton" of the system prompt rather than the full text.
- * This makes the ID resilient to:
- * - Dynamic timestamps, dates, session IDs injected into prompts
- * - User names or account-specific context
- * - Retrieved RAG snippets appended to the base prompt
- * - Minor wording tweaks during prompt iteration
- *
- * The skeleton is: first 500 chars of the prompt with numbers, dates,
- * emails, UUIDs, and hex strings normalized to placeholders.
- */
-export declare function computeBuildId(systemPrompt: string, pluginList: string[], modelId: string): string;
-/**
- * Extract a stable "skeleton" from a system prompt by normalizing
- * dynamic content to placeholders.
- *
- * Normalizes: timestamps, dates, numbers >4 digits, emails, UUIDs,
- * hex strings >8 chars, IP addresses, URLs with path components.
- * Keeps: the structural words, role definitions, tool descriptions,
- * behavioral instructions — the parts that define the agent's identity.
- */
-export declare function extractPromptSkeleton(prompt: string): string;
-/**
- * Classify an agent's role from its label and system prompt content.
- * Uses keyword matching against a role taxonomy — no LLM call needed.
- *
- * Confidence scoring:
- *   90% — role keyword in agent label (explicit naming)
- *   70% — role keyword in SOUL.md "You are a [role]" declaration
- *   40% — role keyword found in general prompt metadata
- *   10% — no match, "General Agent"
- *
- * Multiple signal matches boost confidence by 5% each (capped at 95%).
- */
-export declare function classifyAgent(label: string, systemPrompt: string): AgentClassification;
-/**
- * Enhanced classifier that uses tools + SOUL.md + label.
- * Called when new data (tools or SOUL) becomes available.
- */
-export declare function classifyAgentWithTools(label: string, soulExtract: string, tools: string[]): AgentClassification;
-/** Detect the channel type from OpenClaw prompt metadata. */
-export declare function detectChannel(prompt: string): string | null;
-/** Check if a prompt is a heartbeat prompt. */
-export declare function isHeartbeatPrompt(prompt: string): boolean;
-/** Check if a response is a heartbeat OK response. */
-export declare function isHeartbeatOk(response: string): boolean;