openclaw-plugin-vt-sentinel 0.8.6 → 0.9.1

package/dist/config-manager.d.ts

@@ -2,6 +2,7 @@ import type { SensitiveFilePolicy } from './scanner';
 export type NotifyLevel = 'all' | 'threats_only' | 'silent';
 export type BlockMode = 'quarantine' | 'block_only' | 'log_only';
 export type PresetName = 'balanced' | 'privacy_first' | 'strict_security';
+export type AgentMetadataMode = 'minimal' | 'enhanced';
 export interface FullConfig {
     apiKey?: string;
     watchDirs: string[];
@@ -14,6 +15,11 @@ export interface FullConfig {
     blockMode: BlockMode;
     showCleanScanLogs: boolean;
     configPreset: PresetName;
+    agentDisplayName?: string;
+    agentHumanAlias?: string;
+    agentBio?: string;
+    agentContactEmail?: string;
+    agentMetadataMode?: AgentMetadataMode;
 }
 export type ConfigOverrides = Partial<Omit<FullConfig, 'apiKey'>>;
 export interface ConfigDiff {
@@ -33,6 +39,11 @@ export interface StaticConfig {
     blockMode?: BlockMode;
     showCleanScanLogs?: boolean;
     configPreset?: PresetName;
+    agentDisplayName?: string;
+    agentHumanAlias?: string;
+    agentBio?: string;
+    agentContactEmail?: string;
+    agentMetadataMode?: AgentMetadataMode;
 }
 /**
  * Check if a resolved path is a dangerous filesystem root.

package/dist/config-manager.js

@@ -91,6 +91,10 @@ const VALID_NOTIFY_LEVELS = new Set(['all', 'threats_only', 'silent']);
 const VALID_BLOCK_MODES = new Set(['quarantine', 'block_only', 'log_only']);
 const VALID_PRESETS = new Set(['balanced', 'privacy_first', 'strict_security']);
 const VALID_SENSITIVE_POLICIES = new Set(['ask', 'ask_once', 'always_upload', 'hash_only']);
+const VALID_METADATA_MODES = new Set(['minimal', 'enhanced']);
+const DISPLAY_NAME_RE = /^[a-zA-Z0-9 _-]+$/;
+const HUMAN_ALIAS_RE = /^[a-zA-Z0-9_-]+$/;
+const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
 /**
  * Check if a resolved path is a dangerous filesystem root.
  * Handles Unix / and any Windows drive letter (C:\, d:/, E:\, etc.) case-insensitively.
@@ -190,6 +194,68 @@ function validateOverrides(input) {
             errors.push(`excludeGlobs must be an array of strings`);
         }
     }
+    // --- Agent identity fields ---
+    // Empty string or null clears the field (sets to undefined in overrides).
+    if ('agentDisplayName' in input) {
+        const v = input.agentDisplayName;
+        if (v === '' || v === null) {
+            valid.agentDisplayName = undefined;
+        }
+        else if (typeof v === 'string' && v.length >= 1 && v.length <= 50 && DISPLAY_NAME_RE.test(v)) {
+            valid.agentDisplayName = v;
+        }
+        else {
+            errors.push('agentDisplayName must be 1-50 chars matching [a-zA-Z0-9 _-] (or empty to clear)');
+        }
+    }
+    if ('agentHumanAlias' in input) {
+        const v = input.agentHumanAlias;
+        if (v === '' || v === null) {
+            valid.agentHumanAlias = undefined;
+        }
+        else if (typeof v === 'string' && v.length >= 1 && v.length <= 50 && HUMAN_ALIAS_RE.test(v)) {
+            valid.agentHumanAlias = v;
+        }
+        else {
+            errors.push('agentHumanAlias must be 1-50 chars matching [a-zA-Z0-9_-] (or empty to clear)');
+        }
+    }
+    if ('agentBio' in input) {
+        const v = input.agentBio;
+        if (v === '' || v === null) {
+            valid.agentBio = undefined;
+        }
+        else if (typeof v === 'string' && v.length >= 1 && v.length <= 200) {
+            valid.agentBio = v;
+        }
+        else {
+            errors.push('agentBio must be 1-200 chars (or empty to clear)');
+        }
+    }
+    if ('agentContactEmail' in input) {
+        const v = input.agentContactEmail;
+        if (v === '' || v === null) {
+            valid.agentContactEmail = undefined;
+        }
+        else if (typeof v === 'string' && v.length <= 100 && EMAIL_RE.test(v)) {
+            valid.agentContactEmail = v;
+        }
+        else {
+            errors.push('agentContactEmail must be a valid email (or empty to clear)');
+        }
+    }
+    if ('agentMetadataMode' in input) {
+        const v = input.agentMetadataMode;
+        if (v === '' || v === null) {
+            valid.agentMetadataMode = undefined;
+        }
+        else if (VALID_METADATA_MODES.has(v)) {
+            valid.agentMetadataMode = v;
+        }
+        else {
+            errors.push('agentMetadataMode must be: minimal, enhanced (or empty to clear)');
+        }
+    }
     return { valid, errors };
 }
 // --- Glob matcher ---
@@ -249,6 +315,17 @@ class ConfigManager {
                 result.blockMode = s.blockMode;
             if (s.showCleanScanLogs !== undefined)
                 result.showCleanScanLogs = s.showCleanScanLogs;
+            // Identity
+            if (s.agentDisplayName !== undefined)
+                result.agentDisplayName = s.agentDisplayName;
+            if (s.agentHumanAlias !== undefined)
+                result.agentHumanAlias = s.agentHumanAlias;
+            if (s.agentBio !== undefined)
+                result.agentBio = s.agentBio;
+            if (s.agentContactEmail !== undefined)
+                result.agentContactEmail = s.agentContactEmail;
+            if (s.agentMetadataMode !== undefined)
+                result.agentMetadataMode = s.agentMetadataMode;
         }
         // Layer 4: Overlay runtime overrides
         const o = this.runtimeOverrides;
@@ -272,6 +349,17 @@ class ConfigManager {
             result.showCleanScanLogs = o.showCleanScanLogs;
         if (o.configPreset !== undefined)
             result.configPreset = o.configPreset;
+        // Identity
+        if (o.agentDisplayName !== undefined)
+            result.agentDisplayName = o.agentDisplayName;
+        if (o.agentHumanAlias !== undefined)
+            result.agentHumanAlias = o.agentHumanAlias;
+        if (o.agentBio !== undefined)
+            result.agentBio = o.agentBio;
+        if (o.agentContactEmail !== undefined)
+            result.agentContactEmail = o.agentContactEmail;
+        if (o.agentMetadataMode !== undefined)
+            result.agentMetadataMode = o.agentMetadataMode;
         this.effectiveCache = result;
         return result;
     }

package/dist/index.d.ts

@@ -68,9 +68,16 @@ declare function generateUpdateCommands(opts: {
     stateDir: string;
 }): string;
 export declare function isSelfPath(filePath: string): boolean;
+declare function generateAgentName(): string;
+declare function buildEnhancedBio(eff: {
+    configPreset?: string;
+    autoScan?: boolean;
+}): string;
 export default function vtSentinelPlugin(api: PluginApi): void;
 export declare const _generateUpdateCommands: typeof generateUpdateCommands;
 export declare const _fetchLatestVersion: typeof fetchLatestVersion;
 export declare const _getCurrentVersion: typeof getCurrentVersion;
 export declare const _getStateDir: typeof getStateDir;
+export declare const _generateAgentName: typeof generateAgentName;
+export declare const _buildEnhancedBio: typeof buildEnhancedBio;
 export {};

package/dist/index.js

@@ -36,7 +36,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports._getStateDir = exports._getCurrentVersion = exports._fetchLatestVersion = exports._generateUpdateCommands = void 0;
+exports._buildEnhancedBio = exports._generateAgentName = exports._getStateDir = exports._getCurrentVersion = exports._fetchLatestVersion = exports._generateUpdateCommands = void 0;
 exports.isNewerVersion = isNewerVersion;
 exports.isSelfPath = isSelfPath;
 exports.default = vtSentinelPlugin;
@@ -231,6 +231,27 @@ function isSelfPath(filePath) {
     }
     return normalized.startsWith(SELF_DIR + path.sep) || normalized === SELF_DIR;
 }
+// --- Agent Name Generator ---
+const ADJECTIVES = ['Swift', 'Silent', 'Sharp', 'Bright', 'Steady', 'Bold', 'Keen', 'Quick', 'Iron', 'Steel',
+    'Brave', 'Rapid', 'True', 'Deep', 'Clear', 'Calm', 'Noble', 'Dark', 'Wise', 'Frost'];
+const ANIMALS = ['Falcon', 'Wolf', 'Hawk', 'Fox', 'Lynx', 'Bear', 'Eagle', 'Otter', 'Raven', 'Tiger',
+    'Shark', 'Viper', 'Puma', 'Crane', 'Owl', 'Cobra', 'Stag', 'Mantis', 'Badger', 'Drake'];
+function generateAgentName() {
+    const adj = ADJECTIVES[Math.floor(Math.random() * ADJECTIVES.length)];
+    const animal = ANIMALS[Math.floor(Math.random() * ANIMALS.length)];
+    const hex = Math.floor(Math.random() * 0xFFFF).toString(16).padStart(4, '0');
+    return `Sentinel-${adj}${animal}-${hex}`;
+}
+function buildEnhancedBio(eff) {
+    const osFamily = process.platform === 'darwin' ? 'macos'
+        : process.platform === 'win32' ? 'windows' : 'linux';
+    const parts = [
+        `OpenClaw VT Sentinel on ${osFamily}`,
+        `preset ${eff.configPreset || 'balanced'}`,
+        eff.autoScan !== false ? 'auto-scan on' : 'auto-scan off',
+    ];
+    return parts.join(', ').slice(0, 200);
+}
 // --- Plugin Entry Point ---
 function vtSentinelPlugin(api) {
     let watcher = null;
@@ -255,6 +276,79 @@ function vtSentinelPlugin(api) {
     catch {
         // Best-effort only.
     }
+    /**
+     * Build agent_version string: pluginVer.oc<openclawVer> (max 20 chars, [a-zA-Z0-9.-]+)
+     */
+    function buildAgentVersion() {
+        const pluginVer = getCurrentVersion();
+        try {
+            const meta = api.config?.meta;
+            const ocVer = meta?.version || meta?.lastTouchedVersion || '';
+            const sanitized = String(ocVer).replace(/[^a-zA-Z0-9.-]/g, '').slice(0, 10);
+            if (sanitized)
+                return `${pluginVer}.oc${sanitized}`.slice(0, 20);
+        }
+        catch { }
+        return pluginVer.slice(0, 20);
+    }
+    // VTAI API field constraints (used to sanitize static config values)
+    const VTAI_DISPLAY_NAME_RE = /^[a-zA-Z0-9 _-]+$/;
+    const VTAI_HUMAN_ALIAS_RE = /^[a-zA-Z0-9_-]+$/;
+    const VTAI_EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+    /**
+     * Build registration opts from effective config.
+     * Sanitizes identity fields against VTAI API constraints to prevent
+     * registration failures from invalid static config values.
+     */
+    function buildRegistrationOpts() {
+        const eff = configManager.getEffective();
+        // Resolve display name: config > persisted auto-name > generate new
+        let displayName = eff.agentDisplayName;
+        if (displayName) {
+            // Validate against VTAI constraints: 1-50 chars, [a-zA-Z0-9 _-]+
+            if (displayName.length > 50 || !VTAI_DISPLAY_NAME_RE.test(displayName)) {
+                api.logger.warn(`[VT-Sentinel] Invalid agentDisplayName in config: "${displayName.substring(0, 20)}..." — falling back to auto-generated name`);
+                displayName = undefined;
+            }
+        }
+        if (!displayName) {
+            let autoName = stateStore.getAutoAgentName();
+            if (!autoName) {
+                autoName = generateAgentName();
+                stateStore.setAutoAgentName(autoName);
+            }
+            displayName = autoName;
+        }
+        const regOpts = {
+            agentFamily: 'vt-sentinel',
+            agentVersion: buildAgentVersion(),
+            displayName,
+        };
+        // Validate humanAlias: 1-50 chars, [a-zA-Z0-9_-]+
+        if (eff.agentHumanAlias) {
+            if (eff.agentHumanAlias.length <= 50 && VTAI_HUMAN_ALIAS_RE.test(eff.agentHumanAlias)) {
+                regOpts.humanAlias = eff.agentHumanAlias;
+            }
+            else {
+                api.logger.warn(`[VT-Sentinel] Invalid agentHumanAlias in config — skipping`);
+            }
+        }
+        // Validate contactEmail: max 100 chars, email format
+        if (eff.agentContactEmail) {
+            if (eff.agentContactEmail.length <= 100 && VTAI_EMAIL_RE.test(eff.agentContactEmail)) {
+                regOpts.contactEmail = eff.agentContactEmail;
+            }
+            else {
+                api.logger.warn(`[VT-Sentinel] Invalid agentContactEmail in config — skipping`);
+            }
+        }
+        if (eff.agentMetadataMode === 'enhanced') {
+            const bio = eff.agentBio || buildEnhancedBio(eff);
+            // Validate: 1-200 chars
+            regOpts.defineYourSelf = bio.length <= 200 ? bio : bio.slice(0, 200);
+        }
+        return regOpts;
+    }
     /**
      * Ensure scanner is initialized. Handles API key resolution:
      * 1. User-provided apiKey in config or env → standard VT API
@@ -280,7 +374,7 @@ function vtSentinelPlugin(api) {
             let creds = (0, vt_api_1.loadAgentCredentials)();
             if (!creds) {
                 try {
-                    creds = await (0, vt_api_1.registerAgent)();
+                    creds = await (0, vt_api_1.registerAgent)(buildRegistrationOpts());
                     (0, vt_api_1.saveAgentCredentials)(creds);
                     api.logger.info(`[VT-Sentinel] Auto-registered agent: ${creds.publicHandle}`);
                 }
@@ -878,6 +972,12 @@ function vtSentinelPlugin(api) {
                 updateAvailable: latestKnownVersion != null && !updateCheckFailed,
                 latestVersion: latestKnownVersion || undefined,
                 updateCheckFailed,
+                agentIdentity: {
+                    displayName: eff.agentDisplayName || stateStore.getAutoAgentName() || '(not set)',
+                    publicHandle: (0, vt_api_1.loadAgentCredentials)()?.publicHandle,
+                    metadataMode: eff.agentMetadataMode || 'minimal',
+                    humanAlias: eff.agentHumanAlias,
+                },
             }));
         },
     });
@@ -900,6 +1000,11 @@ function vtSentinelPlugin(api) {
                 excludeGlobs: { type: 'array', items: { type: 'string' }, description: 'Glob patterns for files to skip (e.g., *.log)' },
                 blockMode: { type: 'string', enum: ['quarantine', 'block_only', 'log_only'], description: 'How to handle malicious files' },
                 showCleanScanLogs: { type: 'boolean', description: 'Log clean scan results' },
+                agentDisplayName: { type: 'string', description: 'Display name for VTAI leaderboard (1-50 chars)' },
+                agentHumanAlias: { type: 'string', description: 'Human alias (1-50 chars, no spaces)' },
+                agentBio: { type: 'string', description: 'Agent description for VTAI (1-200 chars)' },
+                agentContactEmail: { type: 'string', description: 'Contact email (optional, privacy-sensitive)' },
+                agentMetadataMode: { type: 'string', enum: ['minimal', 'enhanced'], description: 'Metadata sent during registration: minimal=display_name only, enhanced=adds OS/preset info' },
                 persist: { type: 'string', enum: ['session', 'state'], description: 'session = until restart, state = saved to disk (default: state)' },
             },
             required: [],
@@ -967,7 +1072,13 @@ function vtSentinelPlugin(api) {
             if (params.persist !== 'session') {
                 stateStore.persistOverrides(configManager.getRuntimeOverrides());
             }
-            return textResponse((0, status_renderer_1.renderConfigChangeResult)(diff, newConfig));
+            let result = (0, status_renderer_1.renderConfigChangeResult)(diff, newConfig);
+            // Hint about re-registration if identity fields changed
+            const identityFields = ['agentDisplayName', 'agentHumanAlias', 'agentBio', 'agentContactEmail', 'agentMetadataMode'];
+            if (diff.changedFields.some(f => identityFields.includes(f))) {
+                result += '\n\nIdentity changes saved. To apply to VTAI leaderboard, use vt_sentinel_re_register { confirm: true }.';
+            }
+            return textResponse(result);
         },
     });
     // --- Tool: vt_sentinel_reset_policy ---
@@ -1068,6 +1179,101 @@ function vtSentinelPlugin(api) {
             }));
         },
     });
+    // --- Tool: vt_sentinel_re_register ---
+    api.registerTool({
+        name: 'vt_sentinel_re_register',
+        description: 'Re-register agent with VTAI to apply identity changes. Creates a new agent identity (new public_handle). Use after changing agentDisplayName or other identity settings.',
+        parameters: {
+            type: 'object',
+            properties: {
+                confirm: { type: 'boolean', description: 'Must be true to proceed (generates new identity)' },
+            },
+            required: [],
+        },
+        execute: async (_ctx, rawParams) => {
+            const params = (typeof rawParams === 'object' && rawParams !== null) ? rawParams : {};
+            if ('confirm' in params && typeof params.confirm !== 'boolean') {
+                return textResponse('Error: confirm must be true or false');
+            }
+            // Check if using user API key (no VTAI registration)
+            const envKey = process.env.VIRUSTOTAL_API_KEY;
+            if (envKey && envKey !== 'vtai-active') {
+                return textResponse('Re-registration not applicable — using user-provided API key (not VTAI).');
+            }
+            const eff = configManager.getEffective();
+            const currentCreds = (0, vt_api_1.loadAgentCredentials)();
+            // Resolve display name for preview
+            let displayName = eff.agentDisplayName;
+            if (!displayName) {
+                displayName = stateStore.getAutoAgentName() || '(will generate new name)';
+            }
+            if (!params.confirm) {
+                // Preview mode
+                const lines = ['Agent re-registration preview:'];
+                lines.push('');
+                if (currentCreds) {
+                    lines.push(`  Current handle: ${currentCreds.publicHandle}`);
+                    lines.push(`  Registered at: ${currentCreds.registeredAt}`);
+                }
+                else {
+                    lines.push('  No current registration found.');
+                }
+                lines.push('');
+                lines.push('  New registration will use:');
+                lines.push(`    display_name: ${displayName}`);
+                if (eff.agentHumanAlias)
+                    lines.push(`    human_alias: ${eff.agentHumanAlias}`);
+                if (eff.agentMetadataMode === 'enhanced') {
+                    lines.push(`    define_your_self: ${eff.agentBio || buildEnhancedBio(eff)}`);
+                }
+                if (eff.agentContactEmail)
+                    lines.push(`    contact_email: (set)`);
+                lines.push('');
+                lines.push('WARNING: This creates a NEW agent identity with a new public_handle.');
+                lines.push('The old handle will remain on the leaderboard as a separate entry.');
+                lines.push('');
+                lines.push('Call with { confirm: true } to proceed.');
+                return textResponse(lines.join('\n'));
+            }
+            // Confirmed — re-register
+            try {
+                // Backup current credentials
+                if (currentCreds) {
+                    const backupPath = (0, vt_api_1.getAgentCredentialsPath)() + '.bak';
+                    fs.writeFileSync(backupPath, JSON.stringify(currentCreds, null, 2), { mode: 0o600 });
+                    // Windows: POSIX mode bits ignored on NTFS — restrict via ACL
+                    if (process.platform === 'win32') {
+                        try {
+                            const { execSync } = require('child_process');
+                            execSync(`icacls "${backupPath}" /inheritance:r /grant:r "%USERNAME%:(F)"`, { stdio: 'ignore' });
+                        }
+                        catch { /* best effort */ }
+                    }
+                }
+                const newCreds = await (0, vt_api_1.registerAgent)(buildRegistrationOpts());
+                (0, vt_api_1.saveAgentCredentials)(newCreds);
+                // Update scanner with new token
+                if (scanner) {
+                    const scanEff = configManager.getEffective();
+                    scanner = new scanner_1.Scanner(newCreds.agentToken, api.logger, scanEff.maxFileSizeMb, scanEff.sensitiveFilePolicy, true);
+                }
+                const lines = ['Agent re-registered successfully:'];
+                lines.push(`  New handle: ${newCreds.publicHandle}`);
+                lines.push(`  Display name: ${buildRegistrationOpts().displayName || displayName}`);
+                if (currentCreds) {
+                    lines.push(`  Previous handle: ${currentCreds.publicHandle} (backup saved)`);
+                }
+                return textResponse(lines.join('\n'));
+            }
+            catch (err) {
+                // Rollback on failure
+                if (currentCreds) {
+                    (0, vt_api_1.saveAgentCredentials)(currentCreds);
+                }
+                return textResponse(`Re-registration failed: ${err.message}\nPrevious credentials restored.`);
+            }
+        },
+    });
     // --- Hook: auto-scan tool results ---
     const handleToolResult = async (event) => {
         const s = await ensureScanner();
@@ -1093,7 +1299,7 @@ function vtSentinelPlugin(api) {
                             'vt_scan_file', 'vt_check_hash', 'vt_upload_consent',
                             'vt_sentinel_status', 'vt_sentinel_configure',
                             'vt_sentinel_reset_policy', 'vt_sentinel_help',
-                            'vt_sentinel_update',
+                            'vt_sentinel_update', 'vt_sentinel_re_register',
                         ],
                     });
                     const injected = injectOnboarding(event, onboardingText);
@@ -1308,7 +1514,7 @@ function vtSentinelPlugin(api) {
     vtSentinelPlugin._computeAutoWatchDirs = computeAutoWatchDirs;
     vtSentinelPlugin._handleWatcherFile = handleWatcherFile;
     vtSentinelPlugin._enrichFromContext = enrichFromContext;
-    api.logger.info('[VT-Sentinel] Plugin loaded — 8 tools + active protection hooks registered (VTAI auto-registration enabled)');
+    api.logger.info('[VT-Sentinel] Plugin loaded — 9 tools + active protection hooks registered (VTAI auto-registration enabled)');
     // Non-blocking update check (fire-and-forget)
     checkForUpdates(api.logger, {
         onNewer: (v) => { latestKnownVersion = v; updateCheckFailed = false; },
@@ -1375,3 +1581,5 @@ exports._generateUpdateCommands = generateUpdateCommands;
 exports._fetchLatestVersion = fetchLatestVersion;
 exports._getCurrentVersion = getCurrentVersion;
 exports._getStateDir = getStateDir;
+exports._generateAgentName = generateAgentName;
+exports._buildEnhancedBio = buildEnhancedBio;

package/dist/state-store.d.ts

@@ -1,8 +1,12 @@
 import type { ConfigOverrides } from './config-manager';
+export interface AgentIdentityState {
+    autoAgentName?: string;
+}
 export interface PersistedState {
-    version: 1;
+    version: 2;
     firstRunShown: Record<string, boolean>;
     runtimeOverrides: ConfigOverrides;
+    agentIdentity?: AgentIdentityState;
 }
 export declare class StateStore {
     private state;
@@ -20,6 +24,9 @@ export declare class StateStore {
     getPersistedOverrides(): ConfigOverrides;
     persistOverrides(overrides: ConfigOverrides): void;
     clearPersistedOverrides(): void;
+    getAgentIdentity(): AgentIdentityState;
+    setAutoAgentName(name: string): void;
+    getAutoAgentName(): string | undefined;
     private scopeKey;
     private load;
     private save;

package/dist/state-store.js

@@ -38,9 +38,10 @@ const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const os = __importStar(require("os"));
 const DEFAULT_STATE = {
-    version: 1,
+    version: 2,
     firstRunShown: {},
     runtimeOverrides: {},
+    agentIdentity: {},
 };
 // --- StateStore ---
 class StateStore {
@@ -75,6 +76,19 @@ class StateStore {
         this.state.runtimeOverrides = {};
         this.save();
     }
+    // --- Agent Identity ---
+    getAgentIdentity() {
+        return { ...(this.state.agentIdentity || {}) };
+    }
+    setAutoAgentName(name) {
+        if (!this.state.agentIdentity)
+            this.state.agentIdentity = {};
+        this.state.agentIdentity.autoAgentName = name;
+        this.save();
+    }
+    getAutoAgentName() {
+        return this.state.agentIdentity?.autoAgentName;
+    }
     // --- Internals ---
     scopeKey(scope) {
         if (scope?.workspaceDir)
@@ -86,16 +100,17 @@ class StateStore {
     load() {
         try {
             const data = JSON.parse(fs.readFileSync(this.filePath, 'utf-8'));
-            if (data && data.version === 1) {
+            if (data && (data.version === 1 || data.version === 2)) {
                 return {
-                    version: 1,
+                    version: 2,
                     firstRunShown: data.firstRunShown || {},
                     runtimeOverrides: data.runtimeOverrides || {},
+                    agentIdentity: data.agentIdentity || {},
                 };
             }
         }
         catch { /* missing or corrupt — use defaults */ }
-        return { ...DEFAULT_STATE, firstRunShown: {}, runtimeOverrides: {} };
+        return { ...DEFAULT_STATE, firstRunShown: {}, runtimeOverrides: {}, agentIdentity: {} };
     }
     save() {
         try {

package/dist/status-renderer.d.ts

@@ -17,6 +17,12 @@ export declare function renderStatus(opts: {
     updateAvailable?: boolean;
     latestVersion?: string;
     updateCheckFailed?: boolean;
+    agentIdentity?: {
+        displayName: string;
+        publicHandle?: string;
+        metadataMode: string;
+        humanAlias?: string;
+    };
 }): string;
 export declare function renderPolicyMatrix(config: FullConfig): string;
 export declare function renderHelp(): string;

package/dist/status-renderer.js

@@ -45,6 +45,19 @@ function renderStatus(opts) {
         lines.push('  Update check: last check failed (network error). Use vt_sentinel_update to retry.');
     }
     lines.push('');
+    // Agent Identity
+    if (opts.agentIdentity) {
+        lines.push('Agent Identity:');
+        lines.push(`  Display name: ${opts.agentIdentity.displayName}`);
+        if (opts.agentIdentity.publicHandle) {
+            lines.push(`  Public handle: ${opts.agentIdentity.publicHandle}`);
+        }
+        lines.push(`  Metadata mode: ${opts.agentIdentity.metadataMode}`);
+        if (opts.agentIdentity.humanAlias) {
+            lines.push(`  Human alias: ${opts.agentIdentity.humanAlias}`);
+        }
+        lines.push('');
+    }
     // Config
     lines.push('Effective Configuration:');
     lines.push(`  Preset: ${opts.presetName}`);
@@ -147,6 +160,12 @@ function renderHelp() {
     lines.push('  vt_sentinel_update { confirm: true }');
     lines.push('    Check for updates and get upgrade instructions');
     lines.push('');
+    lines.push('  vt_sentinel_configure { agentDisplayName: "MySecurityBot", agentMetadataMode: "enhanced" }');
+    lines.push('    Set agent display name and enable enhanced metadata');
+    lines.push('');
+    lines.push('  vt_sentinel_re_register { confirm: true }');
+    lines.push('    Re-register with VTAI to apply identity changes (creates new public_handle)');
+    lines.push('');
     lines.push('PRESETS:');
     lines.push('  balanced (default)');
     lines.push('    Ask before uploading sensitive files. Quarantine malicious. Log all scans.');

package/dist/vt-api.d.ts

@@ -34,11 +34,23 @@ export interface AgentCredentials {
 export declare function getAgentCredentialsPath(): string;
 export declare function loadAgentCredentials(): AgentCredentials | null;
 export declare function saveAgentCredentials(creds: AgentCredentials): void;
+/**
+ * Options for agent registration with VTAI.
+ * All fields optional — sensible defaults applied.
+ */
+export interface RegisterAgentOpts {
+    agentFamily?: string;
+    agentVersion?: string;
+    displayName?: string;
+    humanAlias?: string;
+    defineYourSelf?: string;
+    contactEmail?: string;
+}
 /**
  * Register a new agent with VirusTotal AI API.
  * No authentication required — zero-friction onboarding.
  */
-export declare function registerAgent(version?: string): Promise<AgentCredentials>;
+export declare function registerAgent(opts?: RegisterAgentOpts): Promise<AgentCredentials>;
 export declare function calculateSHA256(filePath: string): Promise<string>;
 export declare class VTApiClient {
     private apiKey;

package/dist/vt-api.js

@@ -86,12 +86,19 @@ function saveAgentCredentials(creds) {
  * Register a new agent with VirusTotal AI API.
  * No authentication required — zero-friction onboarding.
  */
-async function registerAgent(version = '0.2.0') {
-    const resp = await axios_1.default.post(`${VTAI_API_URL}/agents/register`, {
-        agent_family: 'vt-sentinel',
-        agent_version: version,
-        display_name: 'VT Sentinel',
-    }, { timeout: HTTP_TIMEOUT_MS });
+async function registerAgent(opts) {
+    const body = {
+        agent_family: opts?.agentFamily || 'vt-sentinel',
+        agent_version: opts?.agentVersion || '0.2.0',
+        display_name: opts?.displayName || 'VT Sentinel',
+    };
+    if (opts?.humanAlias)
+        body.human_alias = opts.humanAlias;
+    if (opts?.defineYourSelf)
+        body.define_your_self = opts.defineYourSelf;
+    if (opts?.contactEmail)
+        body.contact_email = opts.contactEmail;
+    const resp = await axios_1.default.post(`${VTAI_API_URL}/agents/register`, body, { timeout: HTTP_TIMEOUT_MS });
     return {
         agentId: resp.data.agent_id,
         agentToken: resp.data.agent_token,

package/openclaw.plugin.json

@@ -62,6 +62,28 @@
         "enum": ["balanced", "privacy_first", "strict_security"],
         "default": "balanced",
         "description": "Configuration preset. Individual settings override the preset."
+      },
+      "agentDisplayName": {
+        "type": "string",
+        "description": "Display name for VTAI leaderboard (1-50 chars, [a-zA-Z0-9 _-]+)"
+      },
+      "agentHumanAlias": {
+        "type": "string",
+        "description": "Human alias for VTAI (1-50 chars, no spaces)"
+      },
+      "agentBio": {
+        "type": "string",
+        "description": "Agent description for VTAI define_your_self (1-200 chars)"
+      },
+      "agentContactEmail": {
+        "type": "string",
+        "description": "Contact email for VTAI (optional, privacy-sensitive)"
+      },
+      "agentMetadataMode": {
+        "type": "string",
+        "enum": ["minimal", "enhanced"],
+        "default": "minimal",
+        "description": "What metadata to send during registration. minimal = display_name only. enhanced = also sends OS family, preset, and auto-scan status (no personal data)."
       }
     },
     "required": []
@@ -77,6 +99,11 @@
     "excludeGlobs": { "label": "Exclude File Patterns" },
     "blockMode": { "label": "Block Mode" },
     "showCleanScanLogs": { "label": "Show Clean Scan Logs" },
-    "configPreset": { "label": "Configuration Preset" }
+    "configPreset": { "label": "Configuration Preset" },
+    "agentDisplayName": { "label": "Agent Display Name" },
+    "agentHumanAlias": { "label": "Human Alias" },
+    "agentBio": { "label": "Agent Description" },
+    "agentContactEmail": { "label": "Contact Email", "sensitive": true },
+    "agentMetadataMode": { "label": "Metadata Mode" }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-plugin-vt-sentinel",
-  "version": "0.8.6",
+  "version": "0.9.1",
   "description": "VirusTotal Sentinel for OpenClaw - Malware detection and AI-powered code analysis",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/skills/vt-sentinel/SKILL.md

@@ -148,6 +148,29 @@ vt_sentinel_update {}
 vt_sentinel_update { "confirm": true }
 ```
 
+### `vt_sentinel_re_register` — Re-register Agent Identity
+Re-registers with VTAI using current identity settings. Creates a new `public_handle`.
+Use after changing `agentDisplayName` or other identity settings via `vt_sentinel_configure`.
+
+```
+vt_sentinel_re_register {}
+vt_sentinel_re_register { "confirm": true }
+```
+
+## Agent Identity
+
+Each VT Sentinel instance registers with VTAI and appears on the agent leaderboard.
+By default, a unique name is auto-generated (e.g., `Sentinel-SwiftFalcon-a3f2`).
+
+Configure identity via `vt_sentinel_configure`:
+- `agentDisplayName`: Custom display name for the leaderboard
+- `agentHumanAlias`: Human operator alias (no spaces)
+- `agentBio`: Short description (maps to VTAI `define_your_self`)
+- `agentContactEmail`: Optional contact email
+- `agentMetadataMode`: `minimal` (default, display name only) or `enhanced` (adds OS, preset info — no personal data)
+
+After changing identity settings, use `vt_sentinel_re_register { "confirm": true }` to apply.
+
 ## Active Protection
 
 VT Sentinel automatically protects the system in real-time: