profclaw 0.0.1-beta.1

package/dist/chat/proactive/index.js

@@ -0,0 +1,721 @@
+/**
+ * Proactive Agent Capabilities - Phase 19 Category 6
+ *
+ * Transforms the agent from purely reactive to event-driven and proactive:
+ *   6.1 - TriggerManager: event-driven rule execution with cooldowns
+ *   6.2 - generateSuggestions: post-task follow-up suggestions
+ *   6.3 - HealthMonitor: periodic service health checks with degradation events
+ *   6.4 - gatherContext: auto-context assembly before complex responses
+ *   6.5 - BackgroundResearcher: async research task management
+ */
+import { randomUUID } from 'node:crypto';
+import { EventEmitter } from 'node:events';
+import { freemem, totalmem } from 'node:os';
+import { statfs } from 'node:fs/promises';
+/**
+ * Evaluates a simple condition string against a data record.
+ * Supports: <key> <op> <value> where op is >, <, >=, <=, ==, !=
+ * Returns true when condition is absent (unconditional rule).
+ */
+function evaluateCondition(condition, data) {
+    const match = condition.trim().match(/^(\w+)\s*(>|<|>=|<=|==|!=)\s*(.+)$/);
+    if (!match)
+        return false;
+    const [, key, op, rawValue] = match;
+    const lhs = data[key];
+    // Coerce right-hand side to number if possible, else string
+    const rhs = isNaN(Number(rawValue))
+        ? rawValue.replace(/^['"]|['"]$/g, '')
+        : Number(rawValue);
+    switch (op) {
+        case '>': return lhs > rhs;
+        case '<': return lhs < rhs;
+        case '>=': return lhs >= rhs;
+        case '<=': return lhs <= rhs;
+        case '==': return lhs == rhs; // intentional loose equality
+        case '!=': return lhs != rhs;
+        default: return false;
+    }
+}
+/**
+ * Interpolates {{variable}} placeholders in a template string from data.
+ */
+function interpolate(template, data) {
+    return template.replace(/\{\{(\w+)\}\}/g, (_, key) => {
+        const value = data[key];
+        return value !== undefined ? String(value) : `{{${key}}}`;
+    });
+}
+/**
+ * Executes a single TriggerAction and returns descriptive output.
+ */
+function executeAction(action, data) {
+    const message = action.template ? interpolate(action.template, data) : '';
+    switch (action.type) {
+        case 'notify':
+            console.error(`[proactive] notify target=${action.target ?? 'broadcast'} msg=${message}`);
+            return `notified ${action.target ?? 'broadcast'}: ${message}`;
+        case 'message':
+            console.error(`[proactive] message target=${action.target} msg=${message}`);
+            return `message sent to ${action.target}: ${message}`;
+        case 'workflow':
+            console.error(`[proactive] workflow id=${action.workflowId} triggered`);
+            return `workflow ${action.workflowId} triggered`;
+        case 'log':
+            console.error(`[proactive] log: ${message}`);
+            return `logged: ${message}`;
+    }
+}
+export class TriggerManager {
+    rules = new Map();
+    cooldowns = new Map();
+    addRule(rule) {
+        const id = randomUUID();
+        this.rules.set(id, { ...rule, id });
+        return id;
+    }
+    removeRule(id) {
+        this.cooldowns.delete(id);
+        return this.rules.delete(id);
+    }
+    listRules() {
+        return Array.from(this.rules.values());
+    }
+    setEnabled(id, enabled) {
+        const rule = this.rules.get(id);
+        if (rule) {
+            this.rules.set(id, { ...rule, enabled });
+        }
+    }
+    /**
+     * Fire an event - checks all matching rules and executes their actions.
+     * Respects cooldowns and condition expressions.
+     */
+    async fire(event, data) {
+        const results = [];
+        const now = Date.now();
+        for (const rule of this.rules.values()) {
+            if (rule.event !== event)
+                continue;
+            if (!rule.enabled) {
+                results.push({ ruleId: rule.id, executed: false, skipped: 'disabled' });
+                continue;
+            }
+            const lastFired = this.cooldowns.get(rule.id) ?? 0;
+            if (now - lastFired < rule.cooldownMs) {
+                const remaining = rule.cooldownMs - (now - lastFired);
+                results.push({
+                    ruleId: rule.id,
+                    executed: false,
+                    skipped: `cooldown (${remaining}ms remaining)`,
+                });
+                continue;
+            }
+            if (rule.condition && !evaluateCondition(rule.condition, data)) {
+                results.push({
+                    ruleId: rule.id,
+                    executed: false,
+                    skipped: 'condition-false',
+                });
+                continue;
+            }
+            try {
+                const output = executeAction(rule.action, data);
+                this.cooldowns.set(rule.id, now);
+                results.push({ ruleId: rule.id, executed: true, output });
+            }
+            catch (error) {
+                console.error(`[proactive] TriggerManager action failed for rule ${rule.id}:`, error);
+                results.push({
+                    ruleId: rule.id,
+                    executed: false,
+                    skipped: `action-error: ${error instanceof Error ? error.message : 'Unknown'}`,
+                });
+            }
+        }
+        return results;
+    }
+}
+const SUGGESTION_MAP = {
+    deploy: [
+        {
+            type: 'follow_up',
+            message: 'Run smoke tests to verify the deployment succeeded.',
+            confidence: 0.9,
+            action: { label: 'Run smoke tests', command: 'run smoke tests' },
+        },
+        {
+            type: 'follow_up',
+            message: 'Check application logs for errors after deployment.',
+            confidence: 0.85,
+            action: { label: 'Check logs', command: 'check logs for errors' },
+        },
+        {
+            type: 'tip',
+            message: 'Consider setting up a rollback plan before the next deployment.',
+            confidence: 0.6,
+        },
+    ],
+    test: [
+        {
+            type: 'follow_up',
+            message: (ctx) => `Fix the ${ctx.failedTests ?? 'failing'} failing test(s) before merging.`,
+            confidence: 0.95,
+            action: { label: 'Fix failing tests', command: 'fix failing tests' },
+            when: (ctx) => (ctx.failedTests ?? 0) > 0,
+        },
+        {
+            type: 'tip',
+            message: 'Run tests in debug mode to get more output on failures.',
+            confidence: 0.7,
+            action: { label: 'Debug tests', command: 'run tests in debug mode' },
+            when: (ctx) => (ctx.failedTests ?? 0) > 0,
+        },
+        {
+            type: 'optimization',
+            message: 'All tests passed - consider adding coverage reporting.',
+            confidence: 0.5,
+            when: (ctx) => (ctx.failedTests ?? 0) === 0,
+        },
+    ],
+    'code-review': [
+        {
+            type: 'follow_up',
+            message: 'Apply the suggested changes from the review.',
+            confidence: 0.88,
+            action: { label: 'Apply suggestions', command: 'apply review suggestions' },
+            when: (ctx) => (ctx.appliedSuggestions ?? 0) === 0,
+        },
+        {
+            type: 'follow_up',
+            message: 'Create a pull request once the changes look good.',
+            confidence: 0.8,
+            action: { label: 'Create PR', command: 'create pull request' },
+            when: (ctx) => !ctx.prCreated,
+        },
+    ],
+    debug: [
+        {
+            type: 'follow_up',
+            message: 'Create a fix for the identified bug.',
+            confidence: 0.92,
+            action: { label: 'Create fix', command: 'create a fix for the bug' },
+        },
+        {
+            type: 'follow_up',
+            message: 'Add a regression test to prevent this bug from recurring.',
+            confidence: 0.85,
+            action: { label: 'Add regression test', command: 'add regression test' },
+        },
+    ],
+    'create': [
+        {
+            type: 'follow_up',
+            message: 'Add tests for the newly created file(s).',
+            confidence: 0.87,
+            action: { label: 'Add tests', command: 'add tests for new files' },
+            when: (ctx) => (ctx.createdFiles?.length ?? 0) > 0,
+        },
+        {
+            type: 'follow_up',
+            message: 'Update the documentation to reflect the new additions.',
+            confidence: 0.75,
+            action: { label: 'Update docs', command: 'update documentation' },
+        },
+    ],
+    commit: [
+        {
+            type: 'follow_up',
+            message: 'Push the commit to the remote repository.',
+            confidence: 0.9,
+            action: { label: 'Push to remote', command: 'git push' },
+        },
+        {
+            type: 'follow_up',
+            message: 'Create a pull request for code review.',
+            confidence: 0.8,
+            action: { label: 'Create PR', command: 'create pull request' },
+            when: (ctx) => !ctx.prCreated,
+        },
+    ],
+};
+/**
+ * Detect which task type matches the completed task description.
+ * Returns all matching keys (a task may match multiple).
+ */
+function detectTaskTypes(completedTask) {
+    const lower = completedTask.toLowerCase();
+    return Object.keys(SUGGESTION_MAP).filter((key) => lower.includes(key));
+}
+/**
+ * Generate proactive follow-up suggestions after a task completes.
+ */
+export function generateSuggestions(completedTask, context) {
+    const matchedTypes = detectTaskTypes(completedTask);
+    if (matchedTypes.length === 0)
+        return [];
+    const suggestions = [];
+    const seen = new Set();
+    for (const taskType of matchedTypes) {
+        const templates = SUGGESTION_MAP[taskType] ?? [];
+        for (const tpl of templates) {
+            // Skip duplicates by message
+            if (seen.has(tpl.message))
+                continue;
+            // Evaluate guard condition
+            if (tpl.when && !tpl.when(context))
+                continue;
+            // Handle message that may be a function (for dynamic templates)
+            const message = typeof tpl.message === 'function'
+                ? tpl.message(context)
+                : tpl.message;
+            seen.add(message);
+            suggestions.push({
+                id: randomUUID(),
+                type: tpl.type,
+                message,
+                confidence: tpl.confidence,
+                actionable: tpl.action !== undefined,
+                action: tpl.action,
+            });
+        }
+    }
+    // Sort by confidence descending
+    return suggestions.sort((a, b) => b.confidence - a.confidence);
+}
+const DEFAULT_INTERVAL_MS = 5 * 60 * 1000; // 5 minutes
+const DISK_WARN_THRESHOLD = 0.9; // 90% used
+const MEM_WARN_THRESHOLD = 0.8; // 80% used
+/**
+ * Performs a disk space check. Returns degraded at >= 90% usage.
+ * Uses statfs on the current working directory; falls back gracefully.
+ */
+async function checkDiskSpace() {
+    const start = Date.now();
+    try {
+        const stats = await statfs(process.cwd());
+        const total = stats.blocks * stats.bsize;
+        const free = stats.bfree * stats.bsize;
+        const used = total - free;
+        const ratio = total > 0 ? used / total : 0;
+        const latencyMs = Date.now() - start;
+        if (ratio >= DISK_WARN_THRESHOLD) {
+            return {
+                service: 'disk',
+                status: 'degraded',
+                latencyMs,
+                lastChecked: Date.now(),
+                message: `Disk ${(ratio * 100).toFixed(1)}% full (${formatBytes(free)} free)`,
+            };
+        }
+        return {
+            service: 'disk',
+            status: 'healthy',
+            latencyMs,
+            lastChecked: Date.now(),
+            message: `${(ratio * 100).toFixed(1)}% used`,
+        };
+    }
+    catch (error) {
+        return {
+            service: 'disk',
+            status: 'degraded',
+            latencyMs: Date.now() - start,
+            lastChecked: Date.now(),
+            message: `Check failed: ${error instanceof Error ? error.message : 'Unknown'}`,
+        };
+    }
+}
+/**
+ * Performs a memory usage check. Returns degraded at >= 80% used.
+ */
+async function checkMemoryUsage() {
+    const start = Date.now();
+    const free = freemem();
+    const total = totalmem();
+    const ratio = total > 0 ? (total - free) / total : 0;
+    const latencyMs = Date.now() - start;
+    if (ratio >= MEM_WARN_THRESHOLD) {
+        return {
+            service: 'memory',
+            status: 'degraded',
+            latencyMs,
+            lastChecked: Date.now(),
+            message: `Memory ${(ratio * 100).toFixed(1)}% used (${formatBytes(free)} free)`,
+        };
+    }
+    return {
+        service: 'memory',
+        status: 'healthy',
+        latencyMs,
+        lastChecked: Date.now(),
+        message: `${(ratio * 100).toFixed(1)}% used`,
+    };
+}
+function formatBytes(bytes) {
+    if (bytes >= 1e9)
+        return `${(bytes / 1e9).toFixed(1)}GB`;
+    if (bytes >= 1e6)
+        return `${(bytes / 1e6).toFixed(1)}MB`;
+    return `${(bytes / 1e3).toFixed(1)}KB`;
+}
+export class HealthMonitor extends EventEmitter {
+    checkers = new Map();
+    latest = new Map();
+    timer = null;
+    intervalMs;
+    constructor(intervalMs = DEFAULT_INTERVAL_MS) {
+        super();
+        this.intervalMs = intervalMs;
+        // Register built-in checks
+        this.register('disk', checkDiskSpace);
+        this.register('memory', checkMemoryUsage);
+    }
+    register(service, checker) {
+        this.checkers.set(service, checker);
+    }
+    start() {
+        if (this.timer)
+            return; // already running
+        void this.runAll();
+        this.timer = setInterval(() => void this.runAll(), this.intervalMs);
+    }
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+    }
+    getStatus() {
+        return Array.from(this.latest.values());
+    }
+    /** Subscribe to degradation / down events */
+    onDegraded(callback) {
+        this.on('degraded', callback);
+    }
+    async runAll() {
+        for (const [service, checker] of this.checkers) {
+            try {
+                const result = await checker();
+                const previous = this.latest.get(service);
+                this.latest.set(service, result);
+                const wasOk = !previous || previous.status === 'healthy';
+                const isNowBad = result.status === 'degraded' || result.status === 'down';
+                if (wasOk && isNowBad) {
+                    console.error(`[proactive] health degraded: ${service} - ${result.message ?? result.status}`);
+                    this.emit('degraded', result);
+                }
+            }
+            catch (error) {
+                const bad = {
+                    service,
+                    status: 'down',
+                    lastChecked: Date.now(),
+                    message: `Checker threw: ${error instanceof Error ? error.message : 'Unknown'}`,
+                };
+                this.latest.set(service, bad);
+                console.error(`[proactive] health check error for ${service}:`, error);
+                this.emit('degraded', bad);
+            }
+        }
+    }
+}
+const DEFAULT_GATHER_OPTIONS = {
+    maxSources: 8,
+    maxTokens: 4000,
+    includeFiles: true,
+    includeMemory: true,
+    includeHistory: true,
+};
+/** Rough 4-chars-per-token estimate */
+function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+/** Extract keywords from a query for relevance scoring */
+function extractKeywords(query) {
+    return query
+        .toLowerCase()
+        .replace(/[^\w\s]/g, ' ')
+        .split(/\s+/)
+        .filter((w) => w.length > 2);
+}
+/** Score text relevance against keywords (0-1) */
+function scoreRelevance(text, keywords) {
+    if (keywords.length === 0)
+        return 0;
+    const lower = text.toLowerCase();
+    const hits = keywords.filter((kw) => lower.includes(kw)).length;
+    return hits / keywords.length;
+}
+/**
+ * Attempt to read a file for context. Returns null on error.
+ */
+async function tryReadFile(filePath) {
+    try {
+        const { readFile } = await import('node:fs/promises');
+        const content = await readFile(filePath, 'utf8');
+        return content;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Scan the current working directory for project context files.
+ */
+async function gatherProjectInfo(keywords) {
+    const candidates = [
+        'README.md',
+        'CLAUDE.md',
+        'AGENTS.md',
+        'package.json',
+    ];
+    const sources = [];
+    for (const filename of candidates) {
+        const content = await tryReadFile(`${process.cwd()}/${filename}`);
+        if (!content)
+            continue;
+        const truncated = content.slice(0, 2000); // cap each to avoid token explosion
+        const relevance = scoreRelevance(truncated, keywords);
+        sources.push({ type: 'project_info', path: filename, content: truncated, relevance });
+    }
+    return sources;
+}
+/**
+ * Discover files in cwd that match keywords by filename.
+ * Limits to shallow scan via readdir to stay fast.
+ */
+async function gatherFileContext(keywords) {
+    try {
+        const { readdir } = await import('node:fs/promises');
+        const entries = await readdir(process.cwd(), { withFileTypes: true, recursive: false });
+        const sources = [];
+        for (const entry of entries) {
+            if (!entry.isFile())
+                continue;
+            const relevance = scoreRelevance(entry.name, keywords);
+            if (relevance < 0.2)
+                continue;
+            const content = await tryReadFile(`${process.cwd()}/${entry.name}`);
+            if (!content)
+                continue;
+            const truncated = content.slice(0, 1500);
+            sources.push({
+                type: 'file',
+                path: entry.name,
+                content: truncated,
+                relevance,
+            });
+        }
+        return sources;
+    }
+    catch (error) {
+        console.error('[proactive] gatherFileContext failed:', error);
+        return [];
+    }
+}
+/**
+ * Assemble relevant context before responding to a complex query.
+ * Pulls from project files, memory stubs, and recent conversation stubs.
+ * Actual memory/history integration is via adapters - here we provide the
+ * scaffolding and return placeholder sources when adapters are unavailable.
+ */
+export async function gatherContext(query, options) {
+    const opts = { ...DEFAULT_GATHER_OPTIONS, ...options };
+    const keywords = extractKeywords(query);
+    const allSources = [];
+    // Project info (README, CLAUDE.md, etc.)
+    const projectSources = await gatherProjectInfo(keywords);
+    allSources.push(...projectSources);
+    // Relevant files from cwd
+    if (opts.includeFiles) {
+        const fileSources = await gatherFileContext(keywords);
+        allSources.push(...fileSources);
+    }
+    // Sort by relevance descending, deduplicate by path
+    const seen = new Set();
+    const deduped = allSources
+        .sort((a, b) => b.relevance - a.relevance)
+        .filter((s) => {
+        const key = s.path ?? s.type + s.content.slice(0, 40);
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+    // Respect maxSources and maxTokens
+    const selected = [];
+    let tokenBudget = opts.maxTokens;
+    for (const src of deduped) {
+        if (selected.length >= opts.maxSources)
+            break;
+        const toks = estimateTokens(src.content);
+        if (toks > tokenBudget)
+            continue;
+        selected.push(src);
+        tokenBudget -= toks;
+    }
+    const totalTokens = selected.reduce((sum, s) => sum + estimateTokens(s.content), 0);
+    const summary = selected.length === 0
+        ? 'No relevant context found.'
+        : `Found ${selected.length} context source(s) (~${totalTokens} tokens) relevant to: "${query.slice(0, 80)}"`;
+    return { sources: selected, tokens: totalTokens, summary };
+}
+/** Extract concise search terms from a query string */
+function extractSearchTerms(query) {
+    // Remove stop words and very short tokens
+    const stopWords = new Set([
+        'the', 'a', 'an', 'is', 'are', 'was', 'were', 'be', 'been',
+        'have', 'has', 'had', 'do', 'does', 'did', 'will', 'would',
+        'can', 'could', 'should', 'may', 'might', 'must', 'to', 'of',
+        'in', 'on', 'at', 'for', 'with', 'by', 'from', 'up', 'about',
+        'into', 'through', 'how', 'what', 'when', 'where', 'why', 'which',
+    ]);
+    return query
+        .toLowerCase()
+        .replace(/[^\w\s]/g, ' ')
+        .split(/\s+/)
+        .filter((w) => w.length > 3 && !stopWords.has(w))
+        .slice(0, 6); // cap at 6 terms
+}
+/**
+ * Simulated web search placeholder.
+ * In production the executor delegates this to the web_search tool;
+ * this stub records the request and stores a pending result so callers
+ * can poll and later inject real results via BackgroundResearcher.inject().
+ */
+function buildPendingResults(query, terms) {
+    // Construct a representative placeholder result so callers know what was queried
+    return [
+        {
+            source: 'web_search',
+            title: `Search pending: "${query.slice(0, 60)}"`,
+            snippet: `Key terms extracted: ${terms.join(', ')}. Results will be available once the web_search tool executes.`,
+            relevance: 1.0,
+        },
+    ];
+}
+export class BackgroundResearcher {
+    tasks = new Map();
+    /**
+     * Start a background research task.
+     * Extracts terms, stores the task, and begins async processing.
+     * Pass an AbortSignal to cancel mid-flight.
+     */
+    start(query, signal) {
+        const id = randomUUID();
+        const task = {
+            id,
+            query,
+            status: 'pending',
+            results: [],
+            startedAt: Date.now(),
+        };
+        this.tasks.set(id, task);
+        // Run async without blocking caller
+        void this.run(id, query, signal);
+        return { ...task };
+    }
+    getResults(taskId) {
+        const task = this.tasks.get(taskId);
+        return task ? { ...task } : null;
+    }
+    cancel(taskId) {
+        const task = this.tasks.get(taskId);
+        if (task && (task.status === 'pending' || task.status === 'running')) {
+            this.tasks.set(taskId, {
+                ...task,
+                status: 'failed',
+                completedAt: Date.now(),
+                results: [
+                    ...task.results,
+                    {
+                        source: 'system',
+                        title: 'Cancelled',
+                        snippet: 'Research task was cancelled by caller.',
+                        relevance: 0,
+                    },
+                ],
+            });
+        }
+    }
+    listActive() {
+        return Array.from(this.tasks.values())
+            .filter((t) => t.status === 'pending' || t.status === 'running')
+            .map((t) => ({ ...t }));
+    }
+    /**
+     * Inject real results from an external tool executor (e.g., web_search).
+     * Called by the tool executor once it has fetched actual search results.
+     */
+    inject(taskId, results) {
+        const task = this.tasks.get(taskId);
+        if (!task)
+            return;
+        const scored = results
+            .map((r) => {
+            const terms = extractSearchTerms(task.query);
+            const relevance = terms.length > 0 ? scoreRelevance(r.snippet + ' ' + r.title, terms) : r.relevance;
+            return { ...r, relevance };
+        })
+            .sort((a, b) => b.relevance - a.relevance);
+        this.tasks.set(taskId, {
+            ...task,
+            status: 'completed',
+            results: scored,
+            completedAt: Date.now(),
+        });
+    }
+    async run(id, query, signal) {
+        const task = this.tasks.get(id);
+        if (!task)
+            return;
+        // Mark running
+        this.tasks.set(id, { ...task, status: 'running' });
+        try {
+            if (signal?.aborted) {
+                this.cancel(id);
+                return;
+            }
+            const terms = extractSearchTerms(query);
+            console.error(`[proactive] research started id=${id} terms=[${terms.join(', ')}]`);
+            // Build placeholder results; real results injected via inject()
+            const pending = buildPendingResults(query, terms);
+            if (signal?.aborted) {
+                this.cancel(id);
+                return;
+            }
+            const current = this.tasks.get(id);
+            if (!current || current.status !== 'running')
+                return;
+            this.tasks.set(id, {
+                ...current,
+                status: 'completed',
+                results: pending,
+                completedAt: Date.now(),
+            });
+            console.error(`[proactive] research completed id=${id} results=${pending.length}`);
+        }
+        catch (error) {
+            const current = this.tasks.get(id);
+            if (!current)
+                return;
+            console.error(`[proactive] research failed id=${id}:`, error);
+            this.tasks.set(id, {
+                ...current,
+                status: 'failed',
+                completedAt: Date.now(),
+                results: [
+                    ...current.results,
+                    {
+                        source: 'system',
+                        title: 'Error',
+                        snippet: error instanceof Error ? error.message : 'Unknown error',
+                        relevance: 0,
+                    },
+                ],
+            });
+        }
+    }
+}
+//# sourceMappingURL=index.js.map