qlogicagent 2.13.4 → 2.13.5

package/dist/skills/skill-system/skill-guard.js

@@ -0,0 +1,229 @@
+//-------------------------------------------------------------------------
+// Skill security scanner — portable, zero external dependencies.
+// Mirrors openclaw/src/security/skill-scanner.ts rules but uses DI deps
+// instead of Node.js fs/path directly.
+//-------------------------------------------------------------------------
+const LINE_RULES = [
+    {
+        ruleId: "dangerous-exec",
+        severity: "critical",
+        message: "Shell command execution detected (child_process)",
+        pattern: /\b(exec|execSync|spawn|spawnSync|execFile|execFileSync)\s*\(/,
+        requiresContext: /child_process/,
+    },
+    {
+        ruleId: "dynamic-code-execution",
+        severity: "critical",
+        message: "Dynamic code execution detected",
+        pattern: /\beval\s*\(|new\s+Function\s*\(/,
+    },
+    {
+        ruleId: "crypto-mining",
+        severity: "critical",
+        message: "Possible crypto-mining reference detected",
+        pattern: /stratum\+tcp|stratum\+ssl|coinhive|cryptonight|xmrig/i,
+    },
+    {
+        ruleId: "suspicious-network",
+        severity: "warn",
+        message: "WebSocket connection to non-standard port",
+        pattern: /new\s+WebSocket\s*\(\s*["']wss?:\/\/[^"']*:(\d+)/,
+    },
+];
+const STANDARD_PORTS = new Set([80, 443, 8080, 8443, 3000]);
+const SOURCE_RULES = [
+    {
+        ruleId: "potential-exfiltration",
+        severity: "warn",
+        message: "File read combined with network send — possible data exfiltration",
+        pattern: /readFileSync|readFile/,
+        requiresContext: /\bfetch\b|\bpost\b|http\.request/i,
+    },
+    {
+        ruleId: "obfuscated-code",
+        severity: "warn",
+        message: "Hex-encoded string sequence detected (possible obfuscation)",
+        pattern: /(\\x[0-9a-fA-F]{2}){6,}/,
+    },
+    {
+        ruleId: "obfuscated-code",
+        severity: "warn",
+        message: "Large base64 payload with decode call detected (possible obfuscation)",
+        pattern: /(?:atob|Buffer\.from)\s*\(\s*["'][A-Za-z0-9+/=]{200,}["']/,
+    },
+    {
+        ruleId: "env-harvesting",
+        severity: "critical",
+        message: "Environment variable access combined with network send — possible credential harvesting",
+        pattern: /process\.env/,
+        requiresContext: /\bfetch\b|\bpost\b|http\.request/i,
+    },
+];
+//-------------------------------------------------------------------------
+// Scannable extensions
+//-------------------------------------------------------------------------
+const SCANNABLE_EXTENSIONS = new Set([
+    ".js", ".ts", ".mjs", ".cjs", ".mts", ".cts", ".jsx", ".tsx",
+]);
+const DEFAULT_MAX_SCAN_FILES = 500;
+const DEFAULT_MAX_FILE_BYTES = 1024 * 1024;
+//-------------------------------------------------------------------------
+// Core scanner (operates on source text — no FS dependency)
+//-------------------------------------------------------------------------
+function truncateEvidence(evidence, maxLen = 120) {
+    return evidence.length <= maxLen ? evidence : `${evidence.slice(0, maxLen)}…`;
+}
+/**
+ * Scan a source string for security findings.
+ * This is a pure function — no file I/O.
+ */
+export function scanSource(source, filePath) {
+    const findings = [];
+    const lines = source.split("\n");
+    const matchedLineRules = new Set();
+    // Line rules
+    for (const rule of LINE_RULES) {
+        if (matchedLineRules.has(rule.ruleId))
+            continue;
+        if (rule.requiresContext && !rule.requiresContext.test(source))
+            continue;
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
+            const match = rule.pattern.exec(line);
+            if (!match)
+                continue;
+            // Special: suspicious-network checks port number
+            if (rule.ruleId === "suspicious-network") {
+                const port = parseInt(match[1], 10);
+                if (STANDARD_PORTS.has(port))
+                    continue;
+            }
+            findings.push({
+                ruleId: rule.ruleId,
+                severity: rule.severity,
+                file: filePath,
+                line: i + 1,
+                message: rule.message,
+                evidence: truncateEvidence(line.trim()),
+            });
+            matchedLineRules.add(rule.ruleId);
+            break; // one finding per line-rule per file
+        }
+    }
+    // Source rules
+    const matchedSourceRules = new Set();
+    for (const rule of SOURCE_RULES) {
+        const ruleKey = `${rule.ruleId}::${rule.message}`;
+        if (matchedSourceRules.has(ruleKey))
+            continue;
+        if (!rule.pattern.test(source))
+            continue;
+        if (rule.requiresContext && !rule.requiresContext.test(source))
+            continue;
+        let matchLine = 0;
+        let matchEvidence = "";
+        for (let i = 0; i < lines.length; i++) {
+            if (rule.pattern.test(lines[i])) {
+                matchLine = i + 1;
+                matchEvidence = lines[i].trim();
+                break;
+            }
+        }
+        if (matchLine === 0) {
+            matchLine = 1;
+            matchEvidence = source.slice(0, 120);
+        }
+        findings.push({
+            ruleId: rule.ruleId,
+            severity: rule.severity,
+            file: filePath,
+            line: matchLine,
+            message: rule.message,
+            evidence: truncateEvidence(matchEvidence),
+        });
+        matchedSourceRules.add(ruleKey);
+    }
+    return findings;
+}
+async function walkDirWithLimit(deps, dirPath, maxFiles) {
+    const files = [];
+    const stack = [dirPath];
+    while (stack.length > 0 && files.length < maxFiles) {
+        const currentDir = stack.pop();
+        if (!currentDir)
+            break;
+        let entries;
+        try {
+            entries = deps.fs.readdirSync(currentDir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (files.length >= maxFiles)
+                break;
+            if (entry.name.startsWith(".") || entry.name === "node_modules")
+                continue;
+            const fullPath = deps.path.join(currentDir, entry.name);
+            if (entry.isDirectory()) {
+                stack.push(fullPath);
+            }
+            else if (SCANNABLE_EXTENSIONS.has(deps.path.extname(entry.name).toLowerCase())) {
+                files.push(fullPath);
+            }
+        }
+    }
+    return files;
+}
+/**
+ * Scan an entire skill directory for security issues.
+ * Returns a summary with per-file findings.
+ */
+export async function scanSkillDirectory(deps, skillDir, opts) {
+    const maxFiles = Math.max(1, opts?.maxFiles ?? DEFAULT_MAX_SCAN_FILES);
+    const maxFileBytes = Math.max(1, opts?.maxFileBytes ?? DEFAULT_MAX_FILE_BYTES);
+    const files = opts?.includeFiles && opts.includeFiles.length > 0
+        ? opts.includeFiles
+        : await walkDirWithLimit(deps, skillDir, maxFiles);
+    const allFindings = [];
+    let scannedFiles = 0;
+    for (const filePath of files) {
+        try {
+            const stat = deps.fs.statSync(filePath);
+            if (stat.size > maxFileBytes)
+                continue;
+        }
+        catch {
+            continue;
+        }
+        let source;
+        try {
+            source = await deps.fs.readFile(filePath, "utf-8");
+        }
+        catch {
+            continue;
+        }
+        scannedFiles += 1;
+        const findings = scanSource(source, filePath);
+        allFindings.push(...findings);
+    }
+    return {
+        scannedFiles,
+        critical: allFindings.filter((f) => f.severity === "critical").length,
+        warn: allFindings.filter((f) => f.severity === "warn").length,
+        info: allFindings.filter((f) => f.severity === "info").length,
+        findings: allFindings,
+    };
+}
+/**
+ * Quick check: does this source have any critical findings?
+ */
+export function hasCriticalFindings(source, filePath) {
+    return scanSource(source, filePath).some((f) => f.severity === "critical");
+}
+/**
+ * Check if a file extension is scannable by the guard.
+ */
+export function isScannable(filePath, pathDeps) {
+    return SCANNABLE_EXTENSIONS.has(pathDeps.extname(filePath).toLowerCase());
+}

package/dist/skills/skill-system/skill-lifecycle.d.ts

@@ -0,0 +1,93 @@
+export type SkillLifecycleState = "active" | "stale" | "archived";
+export interface SkillLifecycleRecord {
+    name: string;
+    state: SkillLifecycleState;
+    createdAt: string;
+    lastUsedAt?: string;
+    lastViewedAt?: string;
+    lastPatchedAt?: string;
+    staleAt?: string;
+    archivedAt?: string;
+    pinned: boolean;
+    useCount: number;
+    source: "learned" | "created" | "installed" | "promoted";
+    resourceType?: string;
+    launcherRequired?: boolean;
+    manualReviewRequired?: boolean;
+    sourceTier?: "official" | "community";
+    riskTier?: "R0" | "R1" | "R2" | "R3";
+    artifactDigest?: string;
+    registryResourceId?: string;
+    registryVersion?: string;
+    registrySourceTier?: "official" | "community";
+    registryRiskTier?: "R0" | "R1" | "R2" | "R3";
+    registryEffectiveRiskTier?: "R0" | "R1" | "R2" | "R3";
+    registryKeptSignalAt?: string;
+}
+export interface SkillLifecycleStore {
+    version: 1;
+    records: Record<string, SkillLifecycleRecord>;
+}
+export interface CuratorResult {
+    transitioned: Array<{
+        name: string;
+        from: SkillLifecycleState;
+        to: SkillLifecycleState;
+    }>;
+    skippedPinned: string[];
+}
+export declare function loadLifecycleStore(agentHome: string): SkillLifecycleStore;
+export declare function saveLifecycleStore(agentHome: string, store: SkillLifecycleStore): void;
+/**
+ * Ensure a lifecycle record exists for a skill. Creates one if missing.
+ */
+export declare function ensureRecord(store: SkillLifecycleStore, name: string, source?: SkillLifecycleRecord["source"]): SkillLifecycleRecord;
+/**
+ * Record a skill invocation — resets to active if stale.
+ */
+export declare function recordInvocation(store: SkillLifecycleStore, name: string): void;
+/**
+ * Record that a skill was viewed/listed.
+ */
+export declare function recordView(store: SkillLifecycleStore, name: string): void;
+/**
+ * Record that a skill was edited/patched.
+ */
+export declare function recordPatch(store: SkillLifecycleStore, name: string): void;
+export declare function pinSkill(store: SkillLifecycleStore, name: string): boolean;
+export declare function unpinSkill(store: SkillLifecycleStore, name: string): boolean;
+export declare function isPinned(store: SkillLifecycleStore, name: string): boolean;
+/**
+ * Run curator evaluation on all skills. Transitions states based on inactivity.
+ * Pinned skills are never transitioned.
+ *
+ * Call this on agent idle, periodic timer, or explicit RPC.
+ */
+export declare function runCurator(store: SkillLifecycleStore): CuratorResult;
+/**
+ * Archive a skill on disk: move its directory to `.archive/` subfolder.
+ * Returns true if archival succeeded.
+ */
+export declare function archiveSkillOnDisk(skillsDir: string, skillName: string): boolean;
+/**
+ * Unarchive a skill: move from `.archive/` back to main skills dir.
+ * Resets state to active.
+ */
+export declare function unarchiveSkillOnDisk(skillsDir: string, skillName: string): boolean;
+/**
+ * Execute full curator cycle: evaluate state transitions + archive on disk.
+ * Returns curator result with all transitions made.
+ */
+export declare function executeCuratorCycle(agentHome: string, skillsDir: string): CuratorResult;
+/**
+ * Get all skills in a given state.
+ */
+export declare function getSkillsByState(store: SkillLifecycleStore, state: SkillLifecycleState): SkillLifecycleRecord[];
+/**
+ * Get lifecycle record for a skill. Returns undefined if not tracked.
+ */
+export declare function getLifecycleRecord(store: SkillLifecycleStore, name: string): SkillLifecycleRecord | undefined;
+/**
+ * Remove a lifecycle record (e.g., when skill is deleted).
+ */
+export declare function removeRecord(store: SkillLifecycleStore, name: string): void;

package/dist/skills/skill-system/skill-lifecycle.js

@@ -0,0 +1,236 @@
+//-------------------------------------------------------------------------
+// Skill Lifecycle Manager — state machine + curator + pinned protection.
+//
+// Lifecycle states:
+//   active → stale (after STALE_AFTER_DAYS of inactivity)
+//   stale  → archived (after ARCHIVE_AFTER_DAYS of inactivity)
+//   archived → active (on re-invocation or manual unarchive)
+//
+// Pinned skills are exempt from automatic state transitions.
+//
+// Modeled after Hermes curator.py but adapted for qlogicagent's
+// file-system-first, single-process architecture.
+//-------------------------------------------------------------------------
+import { existsSync, readFileSync, writeFileSync, mkdirSync, renameSync } from "node:fs";
+import { join, dirname } from "node:path";
+//-------------------------------------------------------------------------
+// Constants
+//-------------------------------------------------------------------------
+const STALE_AFTER_DAYS = 30;
+const ARCHIVE_AFTER_DAYS = 90;
+const LIFECYCLE_FILENAME = "skill-lifecycle.json";
+//-------------------------------------------------------------------------
+// Store I/O
+//-------------------------------------------------------------------------
+function getStorePath(agentHome) {
+    return join(agentHome, LIFECYCLE_FILENAME);
+}
+export function loadLifecycleStore(agentHome) {
+    const p = getStorePath(agentHome);
+    try {
+        return JSON.parse(readFileSync(p, "utf8"));
+    }
+    catch {
+        return { version: 1, records: {} };
+    }
+}
+export function saveLifecycleStore(agentHome, store) {
+    const p = getStorePath(agentHome);
+    mkdirSync(dirname(p), { recursive: true });
+    // Atomic write: write to temp file then rename (#11: prevent corruption on concurrent access)
+    const tmp = p + ".tmp";
+    writeFileSync(tmp, JSON.stringify(store, null, 2), "utf8");
+    renameSync(tmp, p);
+}
+//-------------------------------------------------------------------------
+// Record management
+//-------------------------------------------------------------------------
+/**
+ * Ensure a lifecycle record exists for a skill. Creates one if missing.
+ */
+export function ensureRecord(store, name, source = "learned") {
+    if (!store.records[name]) {
+        store.records[name] = {
+            name,
+            state: "active",
+            createdAt: new Date().toISOString(),
+            pinned: false,
+            useCount: 0,
+            source,
+        };
+    }
+    return store.records[name];
+}
+/**
+ * Record a skill invocation — resets to active if stale.
+ */
+export function recordInvocation(store, name) {
+    const rec = ensureRecord(store, name);
+    rec.lastUsedAt = new Date().toISOString();
+    rec.useCount++;
+    // Re-activate stale skills on use
+    if (rec.state === "stale") {
+        rec.state = "active";
+        rec.staleAt = undefined;
+    }
+}
+/**
+ * Record that a skill was viewed/listed.
+ */
+export function recordView(store, name) {
+    const rec = ensureRecord(store, name);
+    rec.lastViewedAt = new Date().toISOString();
+}
+/**
+ * Record that a skill was edited/patched.
+ */
+export function recordPatch(store, name) {
+    const rec = ensureRecord(store, name);
+    rec.lastPatchedAt = new Date().toISOString();
+    // Editing resets to active
+    if (rec.state === "stale") {
+        rec.state = "active";
+        rec.staleAt = undefined;
+    }
+}
+//-------------------------------------------------------------------------
+// Pinned protection
+//-------------------------------------------------------------------------
+export function pinSkill(store, name) {
+    const rec = store.records[name];
+    if (!rec)
+        return false;
+    rec.pinned = true;
+    return true;
+}
+export function unpinSkill(store, name) {
+    const rec = store.records[name];
+    if (!rec)
+        return false;
+    rec.pinned = false;
+    return true;
+}
+export function isPinned(store, name) {
+    return store.records[name]?.pinned ?? false;
+}
+//-------------------------------------------------------------------------
+// Curator — state transitions
+//-------------------------------------------------------------------------
+function getLastActivity(rec) {
+    const candidates = [rec.lastUsedAt, rec.lastViewedAt, rec.lastPatchedAt, rec.createdAt]
+        .filter(Boolean)
+        .map(s => new Date(s));
+    return new Date(Math.max(...candidates.map(d => d.getTime())));
+}
+/**
+ * Run curator evaluation on all skills. Transitions states based on inactivity.
+ * Pinned skills are never transitioned.
+ *
+ * Call this on agent idle, periodic timer, or explicit RPC.
+ */
+export function runCurator(store) {
+    const now = Date.now();
+    const result = { transitioned: [], skippedPinned: [] };
+    for (const [name, rec] of Object.entries(store.records)) {
+        // Only curate agent-created/learned skills (not installed/promoted from hub)
+        if (rec.source === "installed")
+            continue;
+        if (rec.pinned) {
+            if (rec.state !== "active") {
+                result.skippedPinned.push(name);
+            }
+            continue;
+        }
+        const lastActivity = getLastActivity(rec);
+        const daysSinceActivity = (now - lastActivity.getTime()) / (1000 * 60 * 60 * 24);
+        if (rec.state === "active" && daysSinceActivity >= STALE_AFTER_DAYS) {
+            rec.state = "stale";
+            rec.staleAt = new Date().toISOString();
+            result.transitioned.push({ name, from: "active", to: "stale" });
+        }
+        else if (rec.state === "stale" && daysSinceActivity >= ARCHIVE_AFTER_DAYS) {
+            rec.state = "archived";
+            rec.archivedAt = new Date().toISOString();
+            result.transitioned.push({ name, from: "stale", to: "archived" });
+        }
+        else if (rec.state === "stale" && daysSinceActivity < STALE_AFTER_DAYS) {
+            // Re-activate: activity happened since skill was marked stale
+            rec.state = "active";
+            rec.staleAt = undefined;
+            result.transitioned.push({ name, from: "stale", to: "active" });
+        }
+    }
+    return result;
+}
+/**
+ * Archive a skill on disk: move its directory to `.archive/` subfolder.
+ * Returns true if archival succeeded.
+ */
+export function archiveSkillOnDisk(skillsDir, skillName) {
+    const skillDir = join(skillsDir, skillName);
+    if (!existsSync(skillDir))
+        return false;
+    const archiveDir = join(skillsDir, ".archive", skillName);
+    mkdirSync(dirname(archiveDir), { recursive: true });
+    try {
+        renameSync(skillDir, archiveDir);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Unarchive a skill: move from `.archive/` back to main skills dir.
+ * Resets state to active.
+ */
+export function unarchiveSkillOnDisk(skillsDir, skillName) {
+    const archiveDir = join(skillsDir, ".archive", skillName);
+    if (!existsSync(archiveDir))
+        return false;
+    const skillDir = join(skillsDir, skillName);
+    try {
+        renameSync(archiveDir, skillDir);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Execute full curator cycle: evaluate state transitions + archive on disk.
+ * Returns curator result with all transitions made.
+ */
+export function executeCuratorCycle(agentHome, skillsDir) {
+    const store = loadLifecycleStore(agentHome);
+    const result = runCurator(store);
+    // Archive skills that transitioned to "archived"
+    for (const t of result.transitioned) {
+        if (t.to === "archived") {
+            archiveSkillOnDisk(skillsDir, t.name);
+        }
+    }
+    saveLifecycleStore(agentHome, store);
+    return result;
+}
+//-------------------------------------------------------------------------
+// Query helpers
+//-------------------------------------------------------------------------
+/**
+ * Get all skills in a given state.
+ */
+export function getSkillsByState(store, state) {
+    return Object.values(store.records).filter(r => r.state === state);
+}
+/**
+ * Get lifecycle record for a skill. Returns undefined if not tracked.
+ */
+export function getLifecycleRecord(store, name) {
+    return store.records[name];
+}
+/**
+ * Remove a lifecycle record (e.g., when skill is deleted).
+ */
+export function removeRecord(store, name) {
+    delete store.records[name];
+}

package/dist/skills/skill-system/skill-source.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Lightweight per-skill stats stored in `~/.qlogicagent/skill-stats.json`.
+ * Covers learned, promoted, and registry-installed skills.
+ */
+export interface SkillUsageStats {
+    /** Total number of times this skill has been invoked/applied. */
+    invokeCount: number;
+    /** Number of turns where the skill was active and contributed. */
+    activeCount: number;
+    /** Number of times the skill received positive feedback. */
+    positiveCount: number;
+    /** Number of times the skill received negative feedback. */
+    negativeCount: number;
+    /** ISO 8601 timestamp of last use. */
+    lastUsedAt?: string;
+    /** Derived success rate = (invokeCount - negativeCount) / invokeCount */
+    successRate?: number;
+}
+export interface SkillStatsFile {
+    [skillName: string]: SkillUsageStats;
+}
+/**
+ * Record a skill invocation. Fire-and-forget — never throws.
+ * @param agentHome - path to `~/.qlogicagent/`
+ * @param skillName - the skill that was invoked
+ * @param success - whether the invocation completed without error
+ */
+export declare function trackSkillInvocation(agentHome: string, skillName: string, success: boolean): void;
+/**
+ * Read stats for a skill. Returns undefined if no stats recorded.
+ */
+export declare function getSkillStats(agentHome: string, skillName: string): SkillUsageStats | undefined;
+/**
+ * Get all skill stats. Useful for UI display.
+ */
+export declare function getAllSkillStats(agentHome: string): SkillStatsFile;
+/** Reset cache (for testing). */
+export declare function resetStatsCache(): void;

package/dist/skills/skill-system/skill-source.js

@@ -0,0 +1,75 @@
+//-------------------------------------------------------------------------
+// Skill source usage tracking.
+//-------------------------------------------------------------------------
+import { join } from "node:path";
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+let _statsCache = null;
+let _statsDirty = false;
+function getStatsPath(agentHome) {
+    return join(agentHome, "skill-stats.json");
+}
+function loadStats(agentHome) {
+    if (_statsCache)
+        return _statsCache;
+    try {
+        _statsCache = JSON.parse(readFileSync(getStatsPath(agentHome), "utf8"));
+    }
+    catch {
+        _statsCache = {};
+    }
+    return _statsCache;
+}
+function flushStats(agentHome) {
+    if (!_statsDirty || !_statsCache)
+        return;
+    try {
+        mkdirSync(agentHome, { recursive: true });
+        writeFileSync(getStatsPath(agentHome), JSON.stringify(_statsCache, null, 2), "utf8");
+        _statsDirty = false;
+    }
+    catch { /* non-fatal — stats are best-effort */ }
+}
+/**
+ * Record a skill invocation. Fire-and-forget — never throws.
+ * @param agentHome - path to `~/.qlogicagent/`
+ * @param skillName - the skill that was invoked
+ * @param success - whether the invocation completed without error
+ */
+export function trackSkillInvocation(agentHome, skillName, success) {
+    const stats = loadStats(agentHome);
+    if (!stats[skillName]) {
+        stats[skillName] = { invokeCount: 0, activeCount: 0, positiveCount: 0, negativeCount: 0 };
+    }
+    stats[skillName].invokeCount++;
+    stats[skillName].lastUsedAt = new Date().toISOString();
+    if (success) {
+        stats[skillName].positiveCount++;
+    }
+    else {
+        stats[skillName].negativeCount++;
+    }
+    if (stats[skillName].invokeCount > 0) {
+        stats[skillName].successRate =
+            (stats[skillName].invokeCount - stats[skillName].negativeCount) / stats[skillName].invokeCount;
+    }
+    _statsDirty = true;
+    flushStats(agentHome);
+}
+/**
+ * Read stats for a skill. Returns undefined if no stats recorded.
+ */
+export function getSkillStats(agentHome, skillName) {
+    const stats = loadStats(agentHome);
+    return stats[skillName];
+}
+/**
+ * Get all skill stats. Useful for UI display.
+ */
+export function getAllSkillStats(agentHome) {
+    return loadStats(agentHome);
+}
+/** Reset cache (for testing). */
+export function resetStatsCache() {
+    _statsCache = null;
+    _statsDirty = false;
+}