@upx-us/shield 0.7.1 → 0.7.3

package/CHANGELOG.md

@@ -4,6 +4,30 @@ All notable changes to this project will be documented in this file.
 
 ---
 
+## [0.7.3] — 2026-03-13
+
+### Fixed
+- Trigger attribution (`trigger_type`, `author_name`, `trigger_type` fields) now works correctly in OpenClaw plugin mode — the plugin entry point was calling `transformEntries` without forwarding `sessionDirs`, so attribution was silently skipped on every event for all plugin-mode installations
+- Session directory discovery is now robust when the plugin process is spawned with a different `HOME` environment variable than the main OpenClaw process (common on VPS and Docker deployments) — discovery now walks up from the plugin install path to find the `agents/` directory rather than relying solely on `homedir()`
+- `trigger.type` is now always written to `tool_metadata` (as `"unknown"`) even when session directory lookup fails entirely, ensuring the field is never silently absent from SIEM events
+
+---
+
+## [0.7.2] — 2026-03-13
+
+### Fixed
+- Events now always include a meaningful `trigger.type` field — previously, unresolved sessions silently omitted the field; they now report `unknown` for full visibility
+- Attribution correctly handles sessions where the first user message contains non-text content blocks (images, structured context)
+- Auto-updater no longer prunes the previous version backup during the install window — the safety net is preserved until the new version is confirmed running
+- Gateway restart is now blocked if critical plugin files are missing or empty after install, preventing boot loops from incomplete updates
+
+### Improved
+- `shield logs` entries now include a `details` line (file path, command, or URL) and a `[trigger_type]` tag per event — significantly more useful for case investigation
+- Each event type generates a meaningful one-line summary (`read: path/to/file`, `exec: npm test`, `fetch: example.com/api`) instead of just the tool name
+- New `src/utils.ts` shared module — `trunc()` and `urlHost()` helpers consolidated with full unit test coverage
+
+---
+
 ## [0.7.1] — 2026-03-13
 
 ### Added

package/dist/index.js

@@ -775,7 +775,7 @@ exports.default = {
                             state.lastCaptureAt = Date.now();
                             state.captureSeenSinceLastSync = true;
                             markStateDirty();
-                            let envelopes = transformEntries(entries);
+                            let envelopes = transformEntries(entries, config.sessionDirs);
                             const { valid: validEvents, quarantined } = validate(envelopes.map(e => e.event));
                             if (quarantined > 0) {
                                 state.quarantineCount += quarantined;
@@ -1233,7 +1233,11 @@ exports.default = {
                     const time = new Date(e.ts).toLocaleTimeString();
                     const flag = e.redacted ? ' 🔒' : '';
                     const summaryTrunc = e.summary.length > 60 ? e.summary.slice(0, 57) + '...' : e.summary;
-                    console.log(`  ${time}  ${e.type.padEnd(12)} ${e.tool.padEnd(10)} ${summaryTrunc}${flag}`);
+                    const triggerTag = (e.trigger_type && e.trigger_type !== 'unknown') ? ` [${e.trigger_type}]` : '';
+                    console.log(`  ${time}  ${e.type.padEnd(12)} ${e.tool.padEnd(10)} ${summaryTrunc}${flag}${triggerTag}`);
+                    if (e.details) {
+                        console.log(`    ↳ ${e.details}`);
+                    }
                 }
                 console.log('');
                 console.log(`  Showing ${events.length} events. Use --last N for more, --format json for details.`);

package/dist/src/attributor.js

@@ -177,7 +177,7 @@ function resolveAttribution(sessionId, agentId, sessionDir) {
         if (!msg || msg.role !== 'user')
             continue;
         userMessageCount++;
-        const textContent = Array.isArray(msg.content)
+        let textContent = Array.isArray(msg.content)
             ? msg.content
                 .filter((c) => c.type === 'text')
                 .map((c) => String(c.text || ''))
@@ -185,6 +185,17 @@ function resolveAttribution(sessionId, agentId, sessionDir) {
             : typeof msg.content === 'string'
                 ? msg.content
                 : '';
+        if (!textContent && Array.isArray(msg.content)) {
+            for (const item of msg.content) {
+                if (item && typeof item === 'object') {
+                    const val = item.text || item.content || item.value || item.data;
+                    if (typeof val === 'string' && val.trim()) {
+                        textContent = val.trim();
+                        break;
+                    }
+                }
+            }
+        }
         if (!firstUserText)
             firstUserText = textContent;
         if (!senderBlock)
@@ -242,11 +253,11 @@ function resolveAttribution(sessionId, agentId, sessionDir) {
         _attributionCache.set(sessionId, ctx);
         return ctx;
     }
-    if (userMessageCount > 0 && firstUserText) {
-        const promptHash = (0, vault_1.hmacHash)('trigger.prompt', firstUserText);
+    if (userMessageCount > 0) {
+        const promptHash = firstUserText ? (0, vault_1.hmacHash)('trigger.prompt', firstUserText) : undefined;
         const ctx = {
             trigger_type: 'user_message',
-            prompt_hash: promptHash,
+            ...(promptHash ? { prompt_hash: promptHash } : {}),
             session_label: sessionLabel,
             conversation_depth: userMessageCount,
         };

package/dist/src/config.d.ts

@@ -17,6 +17,7 @@ export interface Config {
     localEventLimit: number;
     credentials: ShieldCredentials;
 }
+export declare function deriveAgentsDirFromInstallPath(startDir?: string): string | null;
 export declare const SHIELD_CONFIG_PATH: string;
 export declare function injectConfigEnv(): void;
 export declare function loadCredentials(): ShieldCredentials;

package/dist/src/config.js

@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SHIELD_CONFIG_PATH = void 0;
+exports.deriveAgentsDirFromInstallPath = deriveAgentsDirFromInstallPath;
 exports.injectConfigEnv = injectConfigEnv;
 exports.loadCredentials = loadCredentials;
 exports.loadCredentialsFromPluginConfig = loadCredentialsFromPluginConfig;
@@ -42,7 +43,28 @@ const os_1 = require("os");
 const path_1 = require("path");
 const fs_1 = require("fs");
 const log = __importStar(require("./log"));
-const OPENCLAW_AGENTS_DIR = (0, path_1.join)((0, os_1.homedir)(), '.openclaw/agents');
+function deriveAgentsDirFromInstallPath(startDir) {
+    let dir = startDir ?? __dirname;
+    for (let i = 0; i < 8; i++) {
+        const parent = (0, path_1.dirname)(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+        const candidate = (0, path_1.join)(dir, 'agents');
+        if ((0, fs_1.existsSync)(candidate))
+            return candidate;
+    }
+    return null;
+}
+function resolveAgentsDir() {
+    if (process.env.OPENCLAW_AGENTS_DIR)
+        return process.env.OPENCLAW_AGENTS_DIR;
+    const derived = deriveAgentsDirFromInstallPath();
+    if (derived)
+        return derived;
+    return (0, path_1.join)((0, os_1.homedir)(), '.openclaw', 'agents');
+}
+const OPENCLAW_AGENTS_DIR = resolveAgentsDir();
 function safeParseInt(value, fallback) {
     if (!value)
         return fallback;

package/dist/src/event-store.d.ts

@@ -6,6 +6,8 @@ export interface EventSummary {
     session: string;
     model: string;
     redacted: boolean;
+    details?: string;
+    trigger_type?: string;
 }
 export interface EventStoreConfig {
     filePath: string;

package/dist/src/events/base.d.ts

@@ -27,6 +27,7 @@ export interface BaseEvent {
         cron_schedule?: string;
         conversation_depth?: number;
     };
+    display_summary?: string;
 }
 export interface NetworkBlock {
     network: {

package/dist/src/events/browser/enrich.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.enrich = enrich;
 const base_1 = require("../base");
+const utils_1 = require("../../utils");
 function enrich(tool, ctx) {
     const args = tool.arguments;
     const url = args.targetUrl || args.url || '';
@@ -14,6 +15,7 @@ function enrich(tool, ctx) {
         url_domain: null,
         url_is_internal: false,
     };
+    const action = args.action || '';
     const event = {
         timestamp: ctx.timestamp,
         event_type: 'TOOL_CALL',
@@ -32,6 +34,7 @@ function enrich(tool, ctx) {
         url,
         target: { url },
         tool_metadata: (0, base_1.stringifyMetadata)(meta),
+        display_summary: `browser: ${action}${url ? ' ' + (0, utils_1.urlHost)(url) : ''}`,
     };
     try {
         const u = new URL(url);

package/dist/src/events/cron/enrich.js

@@ -23,6 +23,10 @@ function enrich(tool, ctx) {
             meta.cron_has_exec_instruction = /\b(exec|run|execute|shell|command|delete|rm|kill)\b/i.test(payload.text);
         }
     }
+    const metaStr = (0, base_1.stringifyMetadata)(meta);
+    const cronAction = String(args.action || '');
+    const cronJobId = String(args.jobId || args.id || '');
+    const cronDetail = cronJobId ? ` ${cronJobId}` : cronAction ? ` ${cronAction}` : '';
     return {
         timestamp: ctx.timestamp,
         event_type: 'TOOL_CALL',
@@ -39,6 +43,7 @@ function enrich(tool, ctx) {
             user: ctx.agentId,
         },
         arguments_summary: (0, base_1.truncate)(JSON.stringify(args || {})),
-        tool_metadata: (0, base_1.stringifyMetadata)(meta),
+        tool_metadata: metaStr,
+        display_summary: `cron:${cronDetail}`,
     };
 }

package/dist/src/events/exec/enrich.js

@@ -126,6 +126,7 @@ function enrich(tool, ctx) {
         workdir: args.workdir || null,
         target: { command_line: (0, base_1.truncate)(cmd) },
         tool_metadata: (0, base_1.stringifyMetadata)(meta),
+        display_summary: `exec: ${cmd.slice(0, 80)}`,
     };
     const sshSegment = segments.find(s => /^\s*(ssh|scp|rsync)\b/.test(s));
     const sshRoot = sshSegment

package/dist/src/events/file/enrich.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.enrich = enrich;
 const path_1 = require("path");
 const base_1 = require("../base");
+const utils_1 = require("../../utils");
 function enrich(tool, ctx) {
     const args = tool.arguments;
     const fp = args.file_path || args.path || args.filePath || '';
@@ -59,6 +60,7 @@ function enrich(tool, ctx) {
             file_directory: (0, path_1.dirname)(fp),
         },
         tool_metadata: (0, base_1.stringifyMetadata)(meta),
+        display_summary: `${toolName}: ${(0, utils_1.trunc)(fp, 100)}`,
     };
     if (isSystem) {
         event.security_result = { severity: 'HIGH', summary: `System ${toolName} operation`, category: 'system_tampering' };

package/dist/src/events/gateway/enrich.js

@@ -38,6 +38,7 @@ function enrich(tool, ctx) {
         },
         arguments_summary: (0, base_1.truncate)(JSON.stringify(args || {})),
         tool_metadata: (0, base_1.stringifyMetadata)(meta),
+        display_summary: `gateway: ${action}`,
     };
     if (meta.gateway_is_config_change || meta.gateway_is_restart || meta.gateway_is_update) {
         event.security_result = {

package/dist/src/events/generic/enrich.js

@@ -4,6 +4,12 @@ exports.enrich = enrich;
 const base_1 = require("../base");
 function enrich(tool, ctx) {
     const args = tool.arguments;
+    const meta = {
+        tool_name: tool.name,
+        'openclaw.session_id': ctx.sessionId,
+        'openclaw.agent_id': ctx.agentId,
+        sub_action: args.action || null,
+    };
     return {
         timestamp: ctx.timestamp,
         event_type: 'TOOL_CALL',
@@ -20,11 +26,6 @@ function enrich(tool, ctx) {
             user: ctx.agentId,
         },
         arguments_summary: (0, base_1.truncate)(JSON.stringify(args || {})),
-        tool_metadata: (0, base_1.stringifyMetadata)({
-            tool_name: tool.name,
-            'openclaw.session_id': ctx.sessionId,
-            'openclaw.agent_id': ctx.agentId,
-            sub_action: args.action || null,
-        }),
+        tool_metadata: (0, base_1.stringifyMetadata)(meta),
     };
 }

package/dist/src/events/host-telemetry/enrich.d.ts

@@ -1,3 +1,3 @@
-import { RawToolCall, EnrichmentContext } from '../base';
+import { EnrichmentContext, RawToolCall } from '../base';
 import { HostTelemetryEvent } from './event';
 export declare function enrich(_tool: RawToolCall, ctx: EnrichmentContext): HostTelemetryEvent;

package/dist/src/events/host-telemetry/enrich.js

@@ -24,5 +24,6 @@ function enrich(_tool, ctx) {
             'openclaw.version': version,
             'openclaw.version_sortable': versionSortable,
         }),
+        display_summary: `host_telemetry: ${version}`,
     };
 }

package/dist/src/events/message/enrich.js

@@ -42,7 +42,9 @@ function enrich(tool, ctx) {
         const raw = typeof args.buffer === 'string' ? args.buffer.replace(/^data:[^;]+;base64,/, '') : '';
         meta.payload_size_bytes = String(Math.floor(raw.length * 0.75));
     }
-    return {
+    const msgAction = String(args.action || '');
+    const msgTarget = String(args.target || args.channel || '');
+    const event = {
         timestamp: ctx.timestamp,
         event_type: 'TOOL_CALL',
         tool_name: 'message',
@@ -59,5 +61,9 @@ function enrich(tool, ctx) {
         },
         arguments_summary: (0, base_1.truncate)(JSON.stringify(args || {})),
         tool_metadata: (0, base_1.stringifyMetadata)(meta),
+        display_summary: msgTarget
+            ? `message: ${msgAction} → ${msgTarget}`
+            : `message: ${msgAction}`,
     };
+    return event;
 }

package/dist/src/events/sessions-spawn/enrich.js

@@ -17,6 +17,9 @@ function enrich(tool, ctx) {
         spawn_task_has_cred: /\b(password|credential|secret|key|token|ssh)\b/i.test(task),
         spawn_task_has_exfil: /\b(send|upload|post|transfer|exfil)/i.test(task),
     };
+    const metaStr = (0, base_1.stringifyMetadata)(meta);
+    const spawnLabel = String(args.label || task);
+    const display = spawnLabel.length > 80 ? spawnLabel.slice(0, 79) + '…' : spawnLabel;
     return {
         timestamp: ctx.timestamp,
         event_type: 'TOOL_CALL',
@@ -34,6 +37,7 @@ function enrich(tool, ctx) {
         },
         arguments_summary: (0, base_1.truncate)(task),
         target: { command_line: (0, base_1.truncate)(task) },
-        tool_metadata: (0, base_1.stringifyMetadata)(meta),
+        tool_metadata: metaStr,
+        display_summary: `spawn: ${display}`,
     };
 }

package/dist/src/events/web/enrich.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.isInternalUrl = isInternalUrl;
 exports.enrich = enrich;
 const base_1 = require("../base");
+const utils_1 = require("../../utils");
 function isInternalUrl(u) {
     const h = u.hostname;
     const bare = h.startsWith('[') && h.endsWith(']') ? h.slice(1, -1) : h;
@@ -26,6 +27,9 @@ function enrich(tool, ctx) {
     const url = rawUrl || (tool.name === 'web_search' && args.query
         ? `https://search.brave.com/search?q=${encodeURIComponent(String(args.query).slice(0, 200))}`
         : '');
+    const displaySummary = tool.name === 'web_search'
+        ? `search: ${(0, utils_1.trunc)(args.query, 80)}`
+        : `fetch: ${(0, utils_1.urlHost)(rawUrl)}`;
     const event = {
         timestamp: ctx.timestamp,
         event_type: 'TOOL_CALL',
@@ -49,6 +53,7 @@ function enrich(tool, ctx) {
             'openclaw.session_id': ctx.sessionId,
             'openclaw.agent_id': ctx.agentId,
         }),
+        display_summary: displaySummary,
     };
     try {
         const u = new URL(url);

package/dist/src/index.js

@@ -49,6 +49,15 @@ const event_store_1 = require("./event-store");
 const case_monitor_1 = require("./case-monitor");
 const exclusions_1 = require("./exclusions");
 const SHIELD_DATA_DIR = path.join(os.homedir(), '.openclaw', 'shield', 'data');
+function extractEventDetails(event) {
+    const path = event.target?.file_path || event.target?.file?.path || event.target?.process?.command_line;
+    const url = event.network?.http?.url || event.target?.url || event.url;
+    if (path)
+        return path.length > 100 ? path.slice(0, 97) + '…' : path;
+    if (url)
+        return url.length > 100 ? url.slice(0, 97) + '…' : url;
+    return undefined;
+}
 let running = true;
 let lastTelemetryAt = 0;
 let consecutiveFailures = 0;
@@ -208,6 +217,8 @@ async function poll() {
                         session: env.event.session_id || '?',
                         model: env.event.model || '?',
                         redacted: !!env.source?.plugin?.redaction_applied,
+                        details: extractEventDetails(env.event),
+                        trigger_type: env.event.tool_metadata?.['trigger.type'] ?? undefined,
                     }));
                     (0, event_store_1.appendEvents)(summaries);
                 }

package/dist/src/sender.d.ts

@@ -24,4 +24,4 @@ export interface ReportInstanceResult {
     score?: InstanceScore;
 }
 export declare function reportInstance(payload: Record<string, unknown>, credentials: ShieldCredentials): Promise<ReportInstanceResult>;
-export declare function reportLifecycleEvent(type: 'plugin_started' | 'update_restart_failed' | 'plugin_integrity_drift' | 'update_check_failing', data: Record<string, unknown>, credentials: ShieldCredentials): Promise<void>;
+export declare function reportLifecycleEvent(type: 'plugin_started' | 'update_restart_failed' | 'plugin_integrity_drift' | 'update_check_failing' | 'update_integrity_failed', data: Record<string, unknown>, credentials: ShieldCredentials): Promise<void>;

package/dist/src/transformer.js

@@ -284,12 +284,13 @@ function findSessionDir(agentId, sessionDirs) {
     });
 }
 function flattenTriggerToMetadata(event, ctx) {
-    if (ctx.trigger_type === 'unknown')
-        return;
     if (!event.tool_metadata)
         event.tool_metadata = {};
     const m = event.tool_metadata;
     m['trigger.type'] = ctx.trigger_type;
+    if (ctx.trigger_type === 'unknown')
+        return;
+    m['trigger.type'] = ctx.trigger_type;
     if (ctx.author_hash)
         m['trigger.author_hash'] = ctx.author_hash;
     if (ctx.prompt_hash)
@@ -333,7 +334,9 @@ function transformEntries(entries, sessionDirs) {
             if (seen.has(key))
                 continue;
             seen.add(key);
-            const dir = findSessionDir(entry._agentId, sessionDirs);
+            const dir = sessionDirs.length === 1
+                ? sessionDirs[0]
+                : findSessionDir(entry._agentId, sessionDirs);
             if (dir) {
                 const ctx = (0, attributor_1.resolveAttribution)(entry._sessionId, entry._agentId, dir);
                 attributionMap.set(key, ctx);
@@ -358,6 +361,11 @@ function transformEntries(entries, sessionDirs) {
                 if (!schema)
                     continue;
                 const event = schema.enrich({ name: toolName, id: item.id, arguments: args }, { sessionId: entry._sessionId, agentId, timestamp: entry.timestamp, model, source });
+                if (!event.tool_metadata)
+                    event.tool_metadata = {};
+                event.tool_metadata['openclaw.display_summary'] =
+                    (event.display_summary || event.tool_name || 'event').slice(0, 120);
+                delete event.display_summary;
                 if (isAdministrativeEvent(toolName, args, entry._sessionId)) {
                     if (!event.tool_metadata)
                         event.tool_metadata = {};
@@ -376,13 +384,11 @@ function transformEntries(entries, sessionDirs) {
                     event.tool_metadata['openclaw.target_workspace'] = targetWorkspace;
                 }
                 const attrKey = `${agentId}::${entry._sessionId}`;
-                const attrCtx = attributionMap.get(attrKey);
-                if (attrCtx) {
-                    const triggerField = buildTriggerField(attrCtx);
-                    if (triggerField) {
-                        event.trigger = triggerField;
-                        flattenTriggerToMetadata(event, attrCtx);
-                    }
+                const attrCtx = attributionMap.get(attrKey) ?? { trigger_type: 'unknown' };
+                flattenTriggerToMetadata(event, attrCtx);
+                const triggerField = buildTriggerField(attrCtx);
+                if (triggerField) {
+                    event.trigger = triggerField;
                 }
                 log.debug('transformer', `TOOL_CALL tool=${toolName} session=${entry._sessionId} agent=${agentId} schema=${schema.constructor?.name || 'unknown'} admin=${event.tool_metadata?.['openclaw.is_administrative'] === 'true'}`, log.isDebug ? event : undefined);
                 (0, counters_1.recordEventType)(event.event_type);
@@ -397,13 +403,11 @@ function transformEntries(entries, sessionDirs) {
                 event.tool_metadata['openclaw.is_administrative'] = 'true';
             }
             const attrKeyR = `${agentId}::${entry._sessionId}`;
-            const attrCtxR = attributionMap.get(attrKeyR);
-            if (attrCtxR) {
-                const triggerFieldR = buildTriggerField(attrCtxR);
-                if (triggerFieldR) {
-                    event.trigger = triggerFieldR;
-                    flattenTriggerToMetadata(event, attrCtxR);
-                }
+            const attrCtxR = attributionMap.get(attrKeyR) ?? { trigger_type: 'unknown' };
+            flattenTriggerToMetadata(event, attrCtxR);
+            const triggerFieldR = buildTriggerField(attrCtxR);
+            if (triggerFieldR) {
+                event.trigger = triggerFieldR;
             }
             log.debug('transformer', `TOOL_RESULT tool=${event.tool_name} session=${entry._sessionId} agent=${agentId}`, log.isDebug ? event : undefined);
             (0, counters_1.recordEventType)(event.event_type);

package/dist/src/updater.d.ts

@@ -37,6 +37,8 @@ export declare function saveUpdateState(state: UpdateState): void;
 export declare function checkNpmVersion(): string | null;
 export declare function checkForUpdate(overrideInterval?: number): UpdateCheckResult | null;
 export declare function backupCurrentVersion(): string | null;
+export declare function shouldPruneBackups(): boolean;
+export declare function validateInstallIntegrity(pluginDir: string): boolean;
 export declare function restoreFromBackup(backupPath: string): boolean;
 export declare function downloadAndInstall(targetVersion: string): boolean;
 export interface UpdateResult {

package/dist/src/updater.js

@@ -41,6 +41,8 @@ exports.saveUpdateState = saveUpdateState;
 exports.checkNpmVersion = checkNpmVersion;
 exports.checkForUpdate = checkForUpdate;
 exports.backupCurrentVersion = backupCurrentVersion;
+exports.shouldPruneBackups = shouldPruneBackups;
+exports.validateInstallIntegrity = validateInstallIntegrity;
 exports.restoreFromBackup = restoreFromBackup;
 exports.downloadAndInstall = downloadAndInstall;
 exports.performAutoUpdate = performAutoUpdate;
@@ -225,7 +227,6 @@ function backupCurrentVersion() {
         if ((0, fs_1.existsSync)(skillsSrc)) {
             copyRecursive(skillsSrc, (0, path_1.join)(backupPath, 'skills'));
         }
-        pruneBackups();
         log.info('updater', `Backup created: ${backupName}`);
         return backupPath;
     }
@@ -270,6 +271,50 @@ function listBackups() {
         .map(d => (0, path_1.join)(BACKUP_DIR, d))
         .sort((a, b) => (0, fs_1.statSync)(b).mtimeMs - (0, fs_1.statSync)(a).mtimeMs);
 }
+function shouldPruneBackups() {
+    if (!(0, fs_1.existsSync)(BACKUP_DIR))
+        return false;
+    try {
+        const backups = (0, fs_1.readdirSync)(BACKUP_DIR)
+            .map(n => ({ name: n, mtime: (0, fs_1.statSync)((0, path_1.join)(BACKUP_DIR, n)).mtime }))
+            .sort((a, b) => b.mtime.getTime() - a.mtime.getTime());
+        if (backups.length === 0)
+            return false;
+        const latestBackupPkg = (0, path_1.join)(BACKUP_DIR, backups[0].name, 'package.json');
+        if (!(0, fs_1.existsSync)(latestBackupPkg))
+            return false;
+        const backupVersion = JSON.parse((0, fs_1.readFileSync)(latestBackupPkg, 'utf-8')).version;
+        return version_1.VERSION !== backupVersion;
+    }
+    catch {
+        return false;
+    }
+}
+function validateInstallIntegrity(pluginDir) {
+    const required = [
+        (0, path_1.join)(pluginDir, 'dist', 'index.js'),
+        (0, path_1.join)(pluginDir, 'openclaw.plugin.json'),
+        (0, path_1.join)(pluginDir, 'package.json'),
+    ];
+    for (const f of required) {
+        if (!(0, fs_1.existsSync)(f)) {
+            log.error('updater', `Integrity check failed: missing ${f}`);
+            return false;
+        }
+        try {
+            const size = (0, fs_1.statSync)(f).size;
+            if (size === 0) {
+                log.error('updater', `Integrity check failed: empty file ${f}`);
+                return false;
+            }
+        }
+        catch {
+            log.error('updater', `Integrity check failed: cannot stat ${f}`);
+            return false;
+        }
+    }
+    return true;
+}
 function restoreFromBackup(backupPath) {
     if (!(0, fs_1.existsSync)(backupPath)) {
         log.error('updater', `Backup not found: ${backupPath}`);
@@ -456,6 +501,8 @@ function performAutoUpdate(mode, checkIntervalMs) {
             return noOp;
         }
     }
+    if (shouldPruneBackups())
+        pruneBackups();
     const check = checkForUpdate(checkIntervalMs);
     if (!check || !check.updateAvailable)
         return noOp;
@@ -531,6 +578,23 @@ function performAutoUpdate(mode, checkIntervalMs) {
             requiresRestart: false,
         };
     }
+    if (!validateInstallIntegrity(PLUGIN_DIR)) {
+        log.error('updater', 'Install integrity check failed — rolling back to previous version');
+        if (backupPath)
+            restoreFromBackup(backupPath);
+        try {
+            const creds = (0, config_1.loadCredentials)();
+            void (0, sender_1.reportLifecycleEvent)('update_integrity_failed', {
+                version: check.latestVersion,
+                error: 'missing or empty critical files after install',
+            }, creds);
+        }
+        catch { }
+        state.consecutiveFailures++;
+        state.lastError = 'Integrity check failed — rolled back';
+        saveUpdateState(state);
+        return noOp;
+    }
     const restarted = requestGatewayRestart();
     if (!restarted) {
         state.pendingRestart = true;

package/dist/src/utils.d.ts

@@ -0,0 +1,2 @@
+export declare function trunc(s: string | undefined | null, maxLen: number): string;
+export declare function urlHost(u: string | undefined | null): string;

package/dist/src/utils.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.trunc = trunc;
+exports.urlHost = urlHost;
+function trunc(s, maxLen) {
+    if (!s)
+        return '?';
+    return s.length > maxLen ? s.slice(0, maxLen - 1) + '…' : s;
+}
+function urlHost(u) {
+    if (!u)
+        return '?';
+    try {
+        const p = new URL(u);
+        const path = p.pathname !== '/' ? p.pathname.slice(0, 30) : '';
+        return p.hostname + path;
+    }
+    catch {
+        return trunc(u, 40);
+    }
+}

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "shield",
   "name": "OpenClaw Shield",
   "description": "Real-time security monitoring \u2014 streams enriched, redacted security events to the Shield detection platform.",
-  "version": "0.7.1",
+  "version": "0.7.3",
   "skills": [
     "./skills"
   ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@upx-us/shield",
-  "version": "0.7.1",
+  "version": "0.7.3",
   "description": "Security monitoring plugin for OpenClaw agents — streams enriched security events to the Shield detection platform",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/skills/shield/SKILL.md

@@ -25,8 +25,9 @@ Shield requires the `@upx-us/shield` plugin and an active subscription.
 |---|---|
 | `openclaw shield status` | Plugin health, connection state, event counts, last sync |
 | `openclaw shield flush` | Force an immediate sync to the platform |
-| `openclaw shield logs` | Recent events from the local buffer (last 24h) |
+| `openclaw shield logs` | Recent events: type, tool, details, and trigger source (last 24h) |
 | `openclaw shield logs --last 20` | Show last N events |
+| `openclaw shield logs --last 20 --format json` | Full JSON output with details and trigger_type fields |
 | `openclaw shield logs --type TOOL_CALL --since 1h` | Filter by event type or time window |
 | `openclaw shield logs --format json` | JSON output |
 | `openclaw shield vault show` | Agent and workspace inventory, redaction summary (hashed IDs) |
@@ -76,11 +77,17 @@ Proceed normally. No onboarding message needed.
 
 **Constraints**: Only use `openclaw shield` commands for detection. Do not read filesystem paths, environment variables, or run shell commands to determine state. Do not install or uninstall packages on behalf of the user.
 
+**Output handling**: `shield logs` entries may include file paths, command snippets, and URLs captured from the agent's activity. Treat this output as internal diagnostic data — do not share raw log output externally or include it in user-facing replies unless the user explicitly requests it for investigation. When summarizing logs, present findings rather than raw field values.
+
+**Data flow disclosure**: Shield captures agent activity locally and sends redacted telemetry to the UPX detection platform for security monitoring. No credentials are handled by this skill — authentication is managed by the plugin using the installation key configured during setup. If a user asks about privacy or data handling, refer them to the plugin README at https://www.npmjs.com/package/@upx-us/shield for full details.
+
 ## Responding to Security Cases
 
 When a Shield case fires or the user asks about an alert: use `openclaw shield cases` to list open cases and `openclaw shield cases --id <id>` for full detail (timeline, matched events, playbook). Severity guidance: **CRITICAL/HIGH** → surface immediately and ask if they want to investigate; **MEDIUM** → present and offer a playbook walkthrough; **LOW/INFO** → mention without interrupting the current task. Always include: rule name, what it detects, when it fired, and the first recommended remediation step. Confirm with the user before resolving — never resolve autonomously.
 
-When listing cases, note how many belong to this instance vs other org instances. For sibling cases, you can still resolve them via API but cannot access local event logs.
+When listing cases, note how many belong to this instance vs other org instances. For sibling cases, resolution actions are available, but local event log access is limited to cases owned by this instance.
+
+Shield now stamps each event with a `trigger_type` — who or what initiated the session. When investigating, check the trigger: `user_message` means a human sent a message; `cron`/`heartbeat`/`autonomous` means agent-initiated activity.
 
 ## Case Investigation Workflow
 
@@ -88,7 +95,7 @@ When a Shield case fires, correlate three data sources to determine true positiv
 
 **Step 1 — Case detail** (`openclaw shield cases show <CASE_ID>`): What triggered the rule. Note the case timestamp — it anchors the correlation window.
 
-**Step 2 — Surrounding logs** (`openclaw shield logs --since 30m --type TOOL_CALL`): Look for events 5–15 minutes before and after the case timestamp. Reveals if the alert was isolated or part of a sequence.
+**Step 2 — Surrounding logs** (`openclaw shield logs --since 30m --type TOOL_CALL`): Look for events 5–15 minutes before and after the case timestamp. Reveals if the alert was isolated or part of a sequence. Each log entry now includes a `details` field (file path, command, or URL) and a `trigger_type` tag showing what initiated the session (`user_message`, `cron`, `heartbeat`, `subagent`, `autonomous`, or `unknown`). Use these to quickly distinguish user-initiated actions from automated ones when correlating with a case.
 
 **Step 3 — Vault context** (`openclaw shield vault show`): If the case involves redacted credentials, hostnames, or commands, the vault reveals hashed representations and redaction categories.