@upx-us/shield 0.7.1 → 0.7.2

package/CHANGELOG.md

@@ -4,6 +4,21 @@ All notable changes to this project will be documented in this file.
 
 ---
 
+## [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

@@ -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/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)
@@ -358,6 +359,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 = {};
@@ -378,10 +384,10 @@ function transformEntries(entries, sessionDirs) {
                 const attrKey = `${agentId}::${entry._sessionId}`;
                 const attrCtx = attributionMap.get(attrKey);
                 if (attrCtx) {
+                    flattenTriggerToMetadata(event, attrCtx);
                     const triggerField = buildTriggerField(attrCtx);
                     if (triggerField) {
                         event.trigger = triggerField;
-                        flattenTriggerToMetadata(event, attrCtx);
                     }
                 }
                 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);
@@ -399,10 +405,10 @@ function transformEntries(entries, sessionDirs) {
             const attrKeyR = `${agentId}::${entry._sessionId}`;
             const attrCtxR = attributionMap.get(attrKeyR);
             if (attrCtxR) {
+                flattenTriggerToMetadata(event, attrCtxR);
                 const triggerFieldR = buildTriggerField(attrCtxR);
                 if (triggerFieldR) {
                     event.trigger = triggerFieldR;
-                    flattenTriggerToMetadata(event, attrCtxR);
                 }
             }
             log.debug('transformer', `TOOL_RESULT tool=${event.tool_name} session=${entry._sessionId} agent=${agentId}`, log.isDebug ? event : undefined);

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.2",
   "skills": [
     "./skills"
   ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@upx-us/shield",
-  "version": "0.7.1",
+  "version": "0.7.2",
   "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) |
@@ -82,13 +83,15 @@ When a Shield case fires or the user asks about an alert: use `openclaw shield c
 
 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.
 
+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
 
 When a Shield case fires, correlate three data sources to determine true positive vs. false positive:
 
 **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.