@upx-us/shield 0.6.5 → 0.6.6

package/CHANGELOG.md

@@ -4,6 +4,23 @@ All notable changes to this project will be documented in this file.
 
 ---
 
+## [0.6.6] — 2026-03-10
+
+### Added
+- **Plugin lifecycle events** — the plugin now reports key lifecycle signals to the USS platform via the existing `PUT /v1/instance` channel (no new endpoint). Signals are forwarded by Cloud Run as an optional `lifecycle_event` field in the instance telemetry PATCH to the platform. Absent on older plugin versions — fully backward compatible.
+  - `plugin_started`: emitted on every successful startup. Includes `version`, `reason` (`'update'` | `'normal'`), and `previous_version` when applicable. Enables the platform to confirm end-to-end update success.
+  - `update_restart_failed`: emitted after all gateway restart retries are exhausted. Includes `new_version`, `running_version`, `attempts`, `error`.
+  - `plugin_integrity_drift`: emitted when `openclaw.json` version diverges from the installed version after a self-update. Includes `installed_version`, `registered_version`.
+  - `update_check_failing`: emitted after 3 consecutive npm registry check failures. Includes `consecutive_failures`, `last_error`, `next_retry_at`.
+
+### Changed
+- `reportPluginEvent()` removed from `sender.ts` — replaced by `reportLifecycleEvent()` which reuses the existing `PUT /v1/instance` telemetry channel.
+
+### Fixed
+- `SHIELD_AUTO_UPDATE=false` environment variable now correctly disables auto-update (was being read as truthy string `'false'`).
+
+---
+
 ## [0.6.5] — 2026-03-09
 
 ### Added

package/dist/index.js

@@ -648,6 +648,18 @@ exports.default = {
                     catch (err) {
                         log.debug('case-monitor', `Direct send setup failed (non-fatal): ${err instanceof Error ? err.message : String(err)}`);
                     }
+                    try {
+                        const updateState = (0, updater_1.loadUpdateState)();
+                        const previousVersion = updateState.rollbackVersion ?? null;
+                        const startReason = previousVersion ? 'update' : 'normal';
+                        const { reportLifecycleEvent } = await Promise.resolve().then(() => __importStar(require('./src/sender')));
+                        void reportLifecycleEvent('plugin_started', {
+                            version: version_1.VERSION,
+                            reason: startReason,
+                            ...(previousVersion ? { previous_version: previousVersion } : {}),
+                        }, credentials);
+                    }
+                    catch { }
                     const autoUpdateMode = pluginConfig.autoUpdate ?? true;
                     log.info('updater', `Startup update check (autoUpdate=${autoUpdateMode}, current=${version_1.VERSION})`);
                     const startupUpdate = (0, updater_1.performAutoUpdate)(autoUpdateMode, 0);

package/dist/src/index.js

@@ -73,7 +73,8 @@ async function poll() {
         (0, event_store_1.initEventStore)(SHIELD_DATA_DIR, { maxEvents: config.localEventLimit });
     }
     log.info('bridge', `Starting — dryRun=${config.dryRun} poll=${config.pollIntervalMs}ms maxEvents=${config.maxEvents || 'unlimited'} redaction=${config.redactionEnabled} logLevel=${process.env.LOG_LEVEL || 'info'}`);
-    const autoUpdateMode = process.env.SHIELD_AUTO_UPDATE ?? true;
+    const _rawEnvStartup = process.env.SHIELD_AUTO_UPDATE;
+    const autoUpdateMode = _rawEnvStartup === 'false' ? false : _rawEnvStartup ?? true;
     log.info('updater', `Startup update check (autoUpdate=${autoUpdateMode}, current=${version_1.VERSION})`);
     const startupUpdate = (0, updater_1.performAutoUpdate)(autoUpdateMode, 0);
     if (startupUpdate.action === "none") {
@@ -147,7 +148,8 @@ async function poll() {
                     continue;
                 }
             }
-            const autoUpdateMode = process.env.SHIELD_AUTO_UPDATE ?? true;
+            const _rawEnvLoop = process.env.SHIELD_AUTO_UPDATE;
+            const autoUpdateMode = _rawEnvLoop === 'false' ? false : _rawEnvLoop ?? true;
             const updateResult = (0, updater_1.performAutoUpdate)(autoUpdateMode);
             if (updateResult.action !== "none") {
                 if (updateResult.action === "notify") {

package/dist/src/sender.d.ts

@@ -24,3 +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>;

package/dist/src/sender.js

@@ -37,6 +37,7 @@ exports.CIRCUIT_BREAKER_THRESHOLD = exports.REQUEST_TIMEOUT_MS = void 0;
 exports._signRequestWithSecret = _signRequestWithSecret;
 exports.sendEvents = sendEvents;
 exports.reportInstance = reportInstance;
+exports.reportLifecycleEvent = reportLifecycleEvent;
 const crypto_1 = require("crypto");
 const log = __importStar(require("./log"));
 const version_1 = require("./version");
@@ -233,3 +234,16 @@ async function reportInstance(payload, credentials) {
         return { ok: false };
     }
 }
+async function reportLifecycleEvent(type, data, credentials) {
+    try {
+        await reportInstance({
+            lifecycle_event: {
+                type,
+                timestamp: new Date().toISOString(),
+                data,
+            },
+        }, credentials);
+    }
+    catch {
+    }
+}

package/dist/src/updater.js

@@ -53,6 +53,8 @@ const os_1 = require("os");
 const crypto_1 = require("crypto");
 const log = __importStar(require("./log"));
 const version_1 = require("./version");
+const config_1 = require("./config");
+const sender_1 = require("./sender");
 const PACKAGE_NAME = '@upx-us/shield';
 const CHECK_INTERVAL_MS = 6 * 60 * 60 * 1000;
 const MIN_CHECK_INTERVAL_MS = 60 * 1000;
@@ -163,13 +165,28 @@ function checkForUpdate(overrideInterval) {
     state.currentVersion = version_1.VERSION;
     if (!latestVersion) {
         state.lastError = 'Failed to query npm registry';
+        state.consecutiveFailures = (state.consecutiveFailures ?? 0) + 1;
         saveUpdateState(state);
+        const FAILURE_THRESHOLD = 3;
+        if (state.consecutiveFailures >= FAILURE_THRESHOLD) {
+            const nextRetryAt = new Date(now + CHECK_INTERVAL_MS).toISOString();
+            try {
+                const creds = (0, config_1.loadCredentials)();
+                void (0, sender_1.reportLifecycleEvent)('update_check_failing', {
+                    consecutive_failures: state.consecutiveFailures,
+                    last_error: state.lastError,
+                    next_retry_at: nextRetryAt,
+                }, creds);
+            }
+            catch { }
+        }
         return null;
     }
     state.latestVersion = latestVersion;
     if (isNewerVersion(version_1.VERSION, latestVersion)) {
         state.updateAvailable = true;
         state.lastError = null;
+        state.consecutiveFailures = 0;
         saveUpdateState(state);
         const classification = classifyUpdate(version_1.VERSION, latestVersion);
         log.info('updater', `Update available: ${version_1.VERSION} → ${latestVersion} (${classification.isPatch ? 'patch' : classification.isMinor ? 'minor' : 'major'})`);
@@ -182,6 +199,7 @@ function checkForUpdate(overrideInterval) {
     }
     state.updateAvailable = false;
     state.lastError = null;
+    state.consecutiveFailures = 0;
     saveUpdateState(state);
     return null;
 }
@@ -302,6 +320,24 @@ function updateOpenClawPluginMetadata(newVersion, shasum) {
         install.installedAt = new Date().toISOString();
         (0, safe_io_1.writeJsonSafe)(configPath, config);
         log.info('updater', `Updated openclaw.json plugin metadata → ${newVersion}`);
+        try {
+            const written = JSON.parse((0, fs_1.readFileSync)(configPath, 'utf-8'));
+            const installedVersion = written?.plugins?.installs?.shield?.version;
+            if (installedVersion !== newVersion) {
+                log.warn('updater', `openclaw.json integrity check failed: expected=${newVersion} got=${installedVersion ?? '(missing)'}`);
+                try {
+                    const creds = (0, config_1.loadCredentials)();
+                    void (0, sender_1.reportLifecycleEvent)('plugin_integrity_drift', {
+                        expected_version: newVersion,
+                        installed_version: installedVersion ?? null,
+                    }, creds);
+                }
+                catch { }
+            }
+        }
+        catch (verifyErr) {
+            log.warn('updater', `openclaw.json read-back failed: ${verifyErr instanceof Error ? verifyErr.message : String(verifyErr)}`);
+        }
     }
     catch (err) {
         log.warn('updater', `Failed to update openclaw.json metadata: ${err instanceof Error ? err.message : String(err)}`);
@@ -386,6 +422,16 @@ function performAutoUpdate(mode, checkIntervalMs) {
             const MAX_RESTART_ATTEMPTS = 5;
             if ((state.restartAttempts ?? 0) >= MAX_RESTART_ATTEMPTS) {
                 log.warn('updater', `Gateway restart failed ${MAX_RESTART_ATTEMPTS}x after update to ${state.currentVersion} — rolling back`);
+                try {
+                    const creds = (0, config_1.loadCredentials)();
+                    void (0, sender_1.reportLifecycleEvent)('update_restart_failed', {
+                        new_version: state.currentVersion,
+                        running_version: version_1.VERSION,
+                        attempts: state.restartAttempts ?? MAX_RESTART_ATTEMPTS,
+                        error: state.lastError ?? 'gateway restart exhausted all retries',
+                    }, creds);
+                }
+                catch { }
                 const backups = listBackups();
                 if (backups.length > 0) {
                     restoreFromBackup(backups[0]);

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.6.5",
+  "version": "0.6.6",
   "skills": [
     "./skills"
   ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@upx-us/shield",
-  "version": "0.6.5",
+  "version": "0.6.6",
   "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",