@lumenflow/agent 1.0.0

package/dist/feedback-review-core.js

@@ -0,0 +1,358 @@
+/**
+ * Feedback Review Core Logic (WU-1598)
+ *
+ * Aggregates .beacon/incidents/*.ndjson and .beacon/memory/memory.jsonl,
+ * clusters by title similarity, scores patterns (frequency x severity x recency),
+ * and outputs prioritised patterns for human review.
+ *
+ * @see {@link tools/__tests__/feedback-review.test.mjs} - Tests
+ * @see {@link tools/feedback-review.mjs} - CLI entry point
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { INCIDENT_SEVERITY } from '@lumenflow/core/lib/wu-constants.js';
+/**
+ * Severity weights for scoring
+ *
+ * Higher severity = higher weight in scoring formula
+ */
+export const SEVERITY_WEIGHTS = {
+    [INCIDENT_SEVERITY.BLOCKER]: 4,
+    [INCIDENT_SEVERITY.MAJOR]: 3,
+    [INCIDENT_SEVERITY.MINOR]: 2,
+    [INCIDENT_SEVERITY.INFO]: 1,
+};
+/**
+ * Default similarity threshold for title clustering
+ *
+ * Titles with similarity >= this threshold are grouped together.
+ * Range: 0-1 where 1 = exact match
+ */
+const SIMILARITY_THRESHOLD = 0.7;
+/**
+ * Recency decay factor (in milliseconds)
+ *
+ * Patterns older than this are weighted less.
+ * Default: 30 days
+ */
+const RECENCY_DECAY_MS = 30 * 24 * 60 * 60 * 1000;
+/**
+ * Duration multipliers
+ */
+const DURATION_MULTIPLIERS = {
+    m: 60 * 1000, // minutes
+    h: 60 * 60 * 1000, // hours
+    d: 24 * 60 * 60 * 1000, // days
+    w: 7 * 24 * 60 * 60 * 1000, // weeks
+};
+/**
+ * Parse duration string to milliseconds
+ *
+ * Supports: 1d (day), 1w (week), 1h (hour), 1m (minute)
+ *
+ * @param duration - Duration string like "7d", "1w"
+ * @returns Milliseconds
+ */
+function parseDuration(duration) {
+    const match = duration.match(/^(\d+)([dwhmDWHM])$/);
+    if (!match) {
+        throw new Error(`Invalid duration format: ${duration}. Use format like "7d", "1w", "24h"`);
+    }
+    const value = Number.parseInt(match[1], 10);
+    const unit = match[2].toLowerCase();
+    // eslint-disable-next-line security/detect-object-injection -- unit is validated by regex
+    return value * DURATION_MULTIPLIERS[unit];
+}
+/**
+ * Load NDJSON file and parse lines
+ *
+ * @param filePath - Path to NDJSON file
+ * @returns Parsed objects
+ */
+async function loadNdjson(filePath) {
+    try {
+        // eslint-disable-next-line security/detect-non-literal-fs-filename -- CLI tool reads known paths
+        const content = await fs.readFile(filePath, 'utf8');
+        const lines = content.trim().split('\n').filter(Boolean);
+        return lines
+            .map((line) => {
+            try {
+                return JSON.parse(line);
+            }
+            catch {
+                // Skip malformed lines
+                return null;
+            }
+        })
+            .filter((item) => item !== null);
+    }
+    catch (err) {
+        if (err instanceof Error && 'code' in err && err.code === 'ENOENT') {
+            return [];
+        }
+        throw err;
+    }
+}
+/**
+ * Load all incidents from .beacon/incidents/*.ndjson
+ *
+ * @param baseDir - Base directory
+ * @returns All incident objects
+ */
+async function loadIncidents(baseDir) {
+    const incidentsDir = path.join(baseDir, '.beacon', 'incidents');
+    let files;
+    try {
+        // eslint-disable-next-line security/detect-non-literal-fs-filename -- CLI tool reads known paths
+        files = await fs.readdir(incidentsDir);
+    }
+    catch (err) {
+        if (err instanceof Error && 'code' in err && err.code === 'ENOENT') {
+            return [];
+        }
+        throw err;
+    }
+    const ndjsonFiles = files.filter((f) => f.endsWith('.ndjson'));
+    const incidents = [];
+    for (const file of ndjsonFiles) {
+        const items = await loadNdjson(path.join(incidentsDir, file));
+        incidents.push(...items);
+    }
+    return incidents;
+}
+/**
+ * Load memory nodes from .beacon/memory/memory.jsonl
+ *
+ * @param baseDir - Base directory
+ * @returns Memory node objects
+ */
+async function loadMemoryNodes(baseDir) {
+    const memoryFile = path.join(baseDir, '.beacon', 'memory', 'memory.jsonl');
+    return loadNdjson(memoryFile);
+}
+/**
+ * Calculate simple Jaccard similarity between two strings
+ *
+ * Uses word-level comparison for better semantic matching.
+ *
+ * @param str1 - First string
+ * @param str2 - Second string
+ * @returns Similarity score 0-1
+ */
+function calculateSimilarity(str1, str2) {
+    if (!str1 || !str2)
+        return 0;
+    if (str1 === str2)
+        return 1;
+    // Normalize and tokenize
+    const normalize = (s) => s
+        .toLowerCase()
+        .replace(/[^\w\s]/g, ' ')
+        .split(/\s+/)
+        .filter(Boolean);
+    const words1 = new Set(normalize(str1));
+    const words2 = new Set(normalize(str2));
+    if (words1.size === 0 || words2.size === 0)
+        return 0;
+    // Jaccard similarity: intersection / union
+    const intersection = new Set([...words1].filter((w) => words2.has(w)));
+    const union = new Set([...words1, ...words2]);
+    return intersection.size / union.size;
+}
+/**
+ * Get display title for a node
+ *
+ * Falls back to content if title not present.
+ *
+ * @param node - Node object
+ * @returns Title or content
+ */
+function getNodeTitle(node) {
+    return node.title ?? node.content ?? '';
+}
+/**
+ * Cluster nodes by title similarity
+ *
+ * Uses simple greedy clustering with Jaccard similarity.
+ *
+ * @param nodes - Nodes to cluster
+ * @param threshold - Similarity threshold
+ * @returns Array of cluster objects
+ */
+export function clusterByTitle(nodes, threshold = SIMILARITY_THRESHOLD) {
+    if (!nodes || nodes.length === 0) {
+        return [];
+    }
+    const clusters = [];
+    const assigned = new Set();
+    for (const node of nodes) {
+        if (assigned.has(node.id))
+            continue;
+        const title = getNodeTitle(node);
+        if (!title) {
+            // Skip nodes without title/content
+            assigned.add(node.id);
+            continue;
+        }
+        // Find or create cluster
+        let bestCluster = null;
+        let bestSimilarity = 0;
+        for (const cluster of clusters) {
+            const similarity = calculateSimilarity(title, cluster.title);
+            if (similarity >= threshold && similarity > bestSimilarity) {
+                bestSimilarity = similarity;
+                bestCluster = cluster;
+            }
+        }
+        if (bestCluster) {
+            bestCluster.nodes.push(node);
+        }
+        else {
+            clusters.push({
+                title,
+                nodes: [node],
+                category: node.category ?? 'uncategorized',
+            });
+        }
+        assigned.add(node.id);
+    }
+    return clusters;
+}
+/**
+ * Score a pattern cluster
+ *
+ * Formula: frequency x average_severity x recency_factor
+ *
+ * @param cluster - Cluster with nodes
+ * @returns Score value
+ */
+export function scorePattern(cluster) {
+    if (!cluster.nodes || cluster.nodes.length === 0) {
+        return 0;
+    }
+    const frequency = cluster.nodes.length;
+    // Average severity weight
+    const severitySum = cluster.nodes.reduce((sum, node) => {
+        const severity = node.severity;
+        const weight = severity
+            ? (SEVERITY_WEIGHTS[severity] ?? SEVERITY_WEIGHTS[INCIDENT_SEVERITY.INFO])
+            : SEVERITY_WEIGHTS[INCIDENT_SEVERITY.INFO];
+        return sum + weight;
+    }, 0);
+    const avgSeverity = severitySum / cluster.nodes.length;
+    // Recency factor: most recent occurrence weighted higher
+    const now = Date.now();
+    const timestamps = cluster.nodes
+        .map((n) => (n.created_at ? new Date(n.created_at).getTime() : 0))
+        .filter((t) => t > 0);
+    let recencyFactor = 1;
+    if (timestamps.length > 0) {
+        const mostRecent = Math.max(...timestamps);
+        const age = now - mostRecent;
+        // Exponential decay: recent = ~1, old (30+ days) = ~0.37
+        recencyFactor = Math.exp(-age / RECENCY_DECAY_MS);
+        // Clamp to minimum 0.1 so old patterns still count
+        recencyFactor = Math.max(0.1, recencyFactor);
+    }
+    return frequency * avgSeverity * recencyFactor;
+}
+/**
+ * Review feedback from incidents and memory nodes
+ *
+ * Main entry point for feedback review logic.
+ *
+ * @param baseDir - Base directory containing .beacon
+ * @param options - Review options
+ * @returns Review result
+ */
+export async function reviewFeedback(baseDir, options = {}) {
+    const { since, minFrequency, category } = options;
+    // Load all data
+    const [incidents, memoryNodes] = await Promise.all([
+        loadIncidents(baseDir),
+        loadMemoryNodes(baseDir),
+    ]);
+    // Merge into unified nodes format
+    let nodes = [
+        ...incidents.map((inc) => ({
+            id: String(inc.id ?? ''),
+            source: 'incident',
+            title: String(inc.title ?? inc.content ?? ''),
+            content: String(inc.content ?? ''),
+            category: String(inc.category ?? 'uncategorized'),
+            severity: String(inc.severity ?? 'info'),
+            created_at: inc.created_at ? String(inc.created_at) : undefined,
+        })),
+        ...memoryNodes.map((mem) => {
+            const metadata = mem.metadata;
+            const tags = mem.tags;
+            return {
+                id: String(mem.id ?? ''),
+                source: 'memory',
+                title: String(mem.content ?? ''), // Memory nodes use content as title
+                content: String(mem.content ?? ''),
+                severity: String(metadata?.severity ?? 'info'),
+                category: String(mem.type ?? tags?.[0] ?? 'uncategorized'),
+                created_at: mem.created_at ? String(mem.created_at) : undefined,
+            };
+        }),
+    ];
+    // Filter by since
+    if (since) {
+        const cutoffMs = Date.now() - parseDuration(since);
+        nodes = nodes.filter((n) => {
+            const timestamp = n.created_at ? new Date(n.created_at).getTime() : 0;
+            return timestamp >= cutoffMs;
+        });
+    }
+    // Filter by category
+    if (category) {
+        nodes = nodes.filter((n) => n.category === category);
+    }
+    const totalNodes = nodes.length;
+    // Cluster by title similarity
+    let clusters = clusterByTitle(nodes);
+    // Filter by minimum frequency
+    if (minFrequency && minFrequency > 0) {
+        clusters = clusters.filter((c) => c.nodes.length >= minFrequency);
+    }
+    // Score and sort patterns
+    const patterns = clusters
+        .map((cluster) => ({
+        title: cluster.title,
+        frequency: cluster.nodes.length,
+        category: cluster.category,
+        score: scorePattern(cluster),
+        firstSeen: cluster.nodes
+            .map((n) => n.created_at)
+            .filter((c) => c !== undefined)
+            .sort()[0],
+        lastSeen: cluster.nodes
+            .map((n) => n.created_at)
+            .filter((c) => c !== undefined)
+            .sort()
+            .slice(-1)[0],
+        examples: cluster.nodes.slice(0, 3).map((n) => ({
+            id: n.id,
+            severity: n.severity,
+            source: n.source,
+        })),
+    }))
+        .sort((a, b) => b.score - a.score);
+    // Calculate summary
+    const categoryCounts = new Map();
+    for (const p of patterns) {
+        const cat = p.category ?? 'uncategorized';
+        categoryCounts.set(cat, (categoryCounts.get(cat) ?? 0) + p.frequency);
+    }
+    const topCategory = [...categoryCounts.entries()].sort(([, a], [, b]) => b - a)[0]?.[0] ?? null;
+    return {
+        success: true,
+        patterns,
+        summary: {
+            totalNodes,
+            totalClusters: patterns.length,
+            topCategory,
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @lumenflow/agent - Agent session management
+ * @module @lumenflow/agent
+ */
+export * from './agent-incidents.js';
+export * from './agent-session.js';
+export * from './agent-verification.js';
+export * from './auto-session-integration.js';
+export * from './feedback-promote-core.js';
+export * from './feedback-review-core.js';

package/dist/index.js

@@ -0,0 +1,10 @@
+/**
+ * @lumenflow/agent - Agent session management
+ * @module @lumenflow/agent
+ */
+export * from './agent-incidents.js';
+export * from './agent-session.js';
+export * from './agent-verification.js';
+export * from './auto-session-integration.js';
+export * from './feedback-promote-core.js';
+export * from './feedback-review-core.js';

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@lumenflow/agent",
+  "version": "1.0.0",
+  "description": "Agent session management for LumenFlow workflow framework",
+  "keywords": [
+    "lumenflow",
+    "workflow",
+    "agent",
+    "session",
+    "logging"
+  ],
+  "homepage": "https://github.com/hellmai/os",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hellmai/os.git",
+    "directory": "packages/@lumenflow/agent"
+  },
+  "license": "Apache-2.0",
+  "author": {
+    "name": "HellmAI",
+    "url": "https://hellm.ai"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.js",
+    "./session": "./dist/agent-session.js",
+    "./incidents": "./dist/agent-incidents.js",
+    "./verification": "./dist/agent-verification.js",
+    "./auto-session": "./dist/auto-session-integration.js",
+    "./feedback-promote": "./dist/feedback-promote-core.js",
+    "./feedback-review": "./dist/feedback-review-core.js",
+    "./dist/*": "./dist/*"
+  },
+  "main": "./dist/index.js",
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "dependencies": {
+    "simple-git": "^3.30.0",
+    "zod": "^4.3.5",
+    "@lumenflow/core": "1.0.0",
+    "@lumenflow/memory": "1.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "vitest": "^2.1.0"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "build:dist": "tsc -p tsconfig.build.json",
+    "pack:dist": "pnpm pack",
+    "clean": "rm -rf dist *.tgz",
+    "test": "vitest run"
+  }
+}