@useconductor/conductor 1.0.0

package/dist/core/audit.js

@@ -0,0 +1,233 @@
+/**
+ * Audit Logger — Stripe-grade audit trail for every action.
+ *
+ * Every tool call, config change, auth event, and plugin lifecycle event
+ * is logged with: timestamp, actor, action, resource, result, metadata.
+ *
+ * Logs are append-only, tamper-evident (SHA-256 chain), and queryable.
+ * Designed for SOC 2 compliance from day one.
+ */
+import fs from 'fs/promises';
+import path from 'path';
+import crypto from 'crypto';
+export class AuditLogger {
+    logDir;
+    currentFile;
+    lastHash;
+    maxFileSize;
+    buffer;
+    flushTimer;
+    constructor(configDir, options) {
+        this.logDir = path.join(configDir, 'audit');
+        this.currentFile = path.join(this.logDir, 'audit.log');
+        this.lastHash = '0000000000000000000000000000000000000000000000000000000000000000';
+        this.maxFileSize = (options?.maxFileSizeMB ?? 100) * 1024 * 1024;
+        this.buffer = [];
+        this.flushTimer = null;
+        const flushInterval = options?.flushIntervalMs ?? 1000;
+        this.flushTimer = setInterval(() => this.flush().catch(() => { }), flushInterval);
+    }
+    /**
+     * Log an audit entry. Appends to buffer, flushes periodically.
+     */
+    async log(entry) {
+        const timestamp = new Date().toISOString();
+        const content = JSON.stringify({ ...entry, timestamp, previousHash: '' });
+        const hash = crypto
+            .createHash('sha256')
+            .update(this.lastHash + content)
+            .digest('hex');
+        const fullEntry = {
+            ...entry,
+            timestamp,
+            previousHash: this.lastHash,
+            hash,
+        };
+        this.buffer.push(fullEntry);
+        this.lastHash = hash;
+        // Flush immediately for security-critical events
+        if (entry.action === 'auth_login' || entry.action === 'auth_failure' || entry.action === 'config_set') {
+            await this.flush();
+        }
+    }
+    /**
+     * Convenience: log a tool call.
+     */
+    async toolCall(actor, tool, input, result, metadata = {}) {
+        await this.log({
+            actor,
+            action: 'tool_call',
+            resource: tool,
+            result,
+            metadata: { input: this.redactSensitive(input), ...metadata },
+        });
+    }
+    /**
+     * Convenience: log a config change.
+     */
+    async configChange(actor, key, oldValue, newValue) {
+        await this.log({
+            actor,
+            action: 'config_set',
+            resource: key,
+            result: 'success',
+            metadata: { old_value: this.redactSensitive(oldValue), new_value: this.redactSensitive(newValue) },
+        });
+    }
+    /**
+     * Convenience: log an auth event.
+     */
+    async authEvent(actor, method, success, metadata = {}) {
+        await this.log({
+            actor,
+            action: success ? 'auth_login' : 'auth_failure',
+            resource: method,
+            result: success ? 'success' : 'failure',
+            metadata,
+        });
+    }
+    /**
+     * Convenience: log a plugin lifecycle event.
+     */
+    async pluginEvent(actor, plugin, action, metadata = {}) {
+        await this.log({
+            actor,
+            action: `plugin_${action}`,
+            resource: plugin,
+            result: 'success',
+            metadata,
+        });
+    }
+    /**
+     * Query audit logs with filters.
+     */
+    async query(options) {
+        const entries = [];
+        try {
+            const files = await fs.readdir(this.logDir);
+            const logFiles = files.filter((f) => f.endsWith('.log')).sort();
+            for (const file of logFiles) {
+                const content = await fs.readFile(path.join(this.logDir, file), 'utf-8');
+                for (const line of content.split('\n').filter((l) => l.trim())) {
+                    try {
+                        const entry = JSON.parse(line);
+                        if (options?.actor && entry.actor !== options.actor)
+                            continue;
+                        if (options?.action && entry.action !== options.action)
+                            continue;
+                        if (options?.resource && entry.resource !== options.resource)
+                            continue;
+                        if (options?.result && entry.result !== options.result)
+                            continue;
+                        if (options?.since && entry.timestamp < options.since)
+                            continue;
+                        entries.push(entry);
+                    }
+                    catch {
+                        // Skip malformed lines
+                    }
+                }
+            }
+        }
+        catch {
+            // No logs yet
+        }
+        const limit = options?.limit ?? 1000;
+        return entries.slice(-limit);
+    }
+    /**
+     * Verify the integrity of the audit log chain.
+     * Returns true if no tampering detected.
+     */
+    async verifyIntegrity() {
+        try {
+            const content = await fs.readFile(this.currentFile, 'utf-8');
+            const lines = content.split('\n').filter((l) => l.trim());
+            let prevHash = '0000000000000000000000000000000000000000000000000000000000000000';
+            for (const line of lines) {
+                const entry = JSON.parse(line);
+                // Reconstruct what the hash should be
+                const expectedHash = crypto
+                    .createHash('sha256')
+                    .update(prevHash + JSON.stringify({ ...entry, previousHash: entry.previousHash }))
+                    .digest('hex');
+                if (entry.hash !== expectedHash) {
+                    return { valid: false, brokenAt: entry.timestamp };
+                }
+                prevHash = entry.hash;
+            }
+            return { valid: true };
+        }
+        catch {
+            return { valid: true }; // No logs = no tampering
+        }
+    }
+    /**
+     * Flush the buffer to disk.
+     */
+    async flush() {
+        if (this.buffer.length === 0)
+            return;
+        const entries = [...this.buffer];
+        this.buffer = [];
+        try {
+            await fs.mkdir(this.logDir, { recursive: true, mode: 0o700 });
+            // Rotate if file is too large
+            try {
+                const stat = await fs.stat(this.currentFile);
+                if (stat.size > this.maxFileSize) {
+                    const rotated = `${this.currentFile}.${Date.now()}.log`;
+                    await fs.rename(this.currentFile, rotated);
+                }
+            }
+            catch {
+                // File doesn't exist yet
+            }
+            const lines = entries.map((e) => JSON.stringify(e)).join('\n') + '\n';
+            await fs.appendFile(this.currentFile, lines, { mode: 0o600 });
+        }
+        catch (err) {
+            // Put entries back in buffer on failure
+            this.buffer.unshift(...entries);
+            throw err;
+        }
+    }
+    /**
+     * Close the logger and flush remaining entries.
+     */
+    async close() {
+        if (this.flushTimer) {
+            clearInterval(this.flushTimer);
+            this.flushTimer = null;
+        }
+        await this.flush();
+    }
+    /**
+     * Redact sensitive values from metadata.
+     */
+    redactSensitive(value) {
+        if (typeof value === 'string') {
+            // Redact anything that looks like a token, key, or password
+            if (/^(ghp_|xoxb_|xapp_|sk-|Bearer |token_|api_key_|password)/i.test(value)) {
+                return '[REDACTED]';
+            }
+            if (value.length > 1000) {
+                return `[truncated: ${value.length} chars]`;
+            }
+        }
+        if (typeof value === 'object' && value !== null) {
+            const result = {};
+            for (const [k, v] of Object.entries(value)) {
+                if (/secret|token|key|password|auth/i.test(k)) {
+                    result[k] = '[REDACTED]';
+                }
+                else {
+                    result[k] = v;
+                }
+            }
+            return result;
+        }
+        return value;
+    }
+}
+//# sourceMappingURL=audit.js.map

package/dist/core/audit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.js","sourceRoot":"","sources":["../../src/core/audit.ts"],"names":[],"mappings":"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"}

package/dist/core/circuit-breaker.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Circuit Breaker — prevents cascading failures.
+ *
+ * When a tool or dependency fails repeatedly, the circuit opens and
+ * subsequent calls fail fast without hitting the failing service.
+ * After a cooldown period, the circuit half-opens to test recovery.
+ *
+ * States: CLOSED (normal) → OPEN (failing) → HALF_OPEN (testing) → CLOSED
+ */
+export type CircuitState = 'closed' | 'open' | 'half_open';
+export interface CircuitBreakerOptions {
+    /** Number of failures before opening the circuit */
+    failureThreshold: number;
+    /** Time in ms before attempting recovery */
+    recoveryTimeout: number;
+    /** Number of successful calls in half_open to close the circuit */
+    successThreshold: number;
+}
+export declare class CircuitBreaker {
+    private state;
+    private failures;
+    private successes;
+    private lastFailureAt;
+    private options;
+    constructor(options?: Partial<CircuitBreakerOptions>);
+    getState(): CircuitState;
+    /**
+     * Execute a function through the circuit breaker.
+     * Throws CircuitOpenError if the circuit is open.
+     */
+    execute<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Record a successful call.
+     */
+    private onSuccess;
+    /**
+     * Record a failed call.
+     */
+    private onFailure;
+    /**
+     * Reset the circuit breaker to closed state.
+     */
+    reset(): void;
+    /**
+     * Get circuit breaker status for health checks.
+     */
+    getStatus(): {
+        state: CircuitState;
+        failures: number;
+        successes: number;
+    };
+}
+export declare class CircuitOpenError extends Error {
+    constructor(message: string);
+}
+//# sourceMappingURL=circuit-breaker.d.ts.map

package/dist/core/circuit-breaker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"circuit-breaker.d.ts","sourceRoot":"","sources":["../../src/core/circuit-breaker.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;AAE3D,MAAM,WAAW,qBAAqB;IACpC,oDAAoD;IACpD,gBAAgB,EAAE,MAAM,CAAC;IACzB,4CAA4C;IAC5C,eAAe,EAAE,MAAM,CAAC;IACxB,mEAAmE;IACnE,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAQD,qBAAa,cAAc;IACzB,OAAO,CAAC,KAAK,CAA0B;IACvC,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,OAAO,CAAwB;gBAE3B,OAAO,CAAC,EAAE,OAAO,CAAC,qBAAqB,CAAC;IAIpD,QAAQ,IAAI,YAAY;IAWxB;;;OAGG;IACG,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAiBlD;;OAEG;IACH,OAAO,CAAC,SAAS;IAYjB;;OAEG;IACH,OAAO,CAAC,SAAS;IAajB;;OAEG;IACH,KAAK,IAAI,IAAI;IAOb;;OAEG;IACH,SAAS,IAAI;QAAE,KAAK,EAAE,YAAY,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE;CAO1E;AAED,qBAAa,gBAAiB,SAAQ,KAAK;gBAC7B,OAAO,EAAE,MAAM;CAI5B"}

package/dist/core/circuit-breaker.js

@@ -0,0 +1,107 @@
+/**
+ * Circuit Breaker — prevents cascading failures.
+ *
+ * When a tool or dependency fails repeatedly, the circuit opens and
+ * subsequent calls fail fast without hitting the failing service.
+ * After a cooldown period, the circuit half-opens to test recovery.
+ *
+ * States: CLOSED (normal) → OPEN (failing) → HALF_OPEN (testing) → CLOSED
+ */
+const DEFAULTS = {
+    failureThreshold: 5,
+    recoveryTimeout: 60_000,
+    successThreshold: 2,
+};
+export class CircuitBreaker {
+    state = 'closed';
+    failures = 0;
+    successes = 0;
+    lastFailureAt = 0;
+    options;
+    constructor(options) {
+        this.options = { ...DEFAULTS, ...options };
+    }
+    getState() {
+        if (this.state === 'open') {
+            // Check if recovery timeout has elapsed
+            if (Date.now() - this.lastFailureAt >= this.options.recoveryTimeout) {
+                this.state = 'half_open';
+                this.successes = 0;
+            }
+        }
+        return this.state;
+    }
+    /**
+     * Execute a function through the circuit breaker.
+     * Throws CircuitOpenError if the circuit is open.
+     */
+    async execute(fn) {
+        const state = this.getState();
+        if (state === 'open') {
+            throw new CircuitOpenError('Circuit breaker is open — call rejected');
+        }
+        try {
+            const result = await fn();
+            this.onSuccess();
+            return result;
+        }
+        catch (err) {
+            this.onFailure();
+            throw err;
+        }
+    }
+    /**
+     * Record a successful call.
+     */
+    onSuccess() {
+        this.failures = 0;
+        if (this.state === 'half_open') {
+            this.successes++;
+            if (this.successes >= this.options.successThreshold) {
+                this.state = 'closed';
+                this.successes = 0;
+            }
+        }
+    }
+    /**
+     * Record a failed call.
+     */
+    onFailure() {
+        this.failures++;
+        this.lastFailureAt = Date.now();
+        if (this.state === 'half_open') {
+            // Any failure in half_open re-opens the circuit
+            this.state = 'open';
+            this.successes = 0;
+        }
+        else if (this.failures >= this.options.failureThreshold) {
+            this.state = 'open';
+        }
+    }
+    /**
+     * Reset the circuit breaker to closed state.
+     */
+    reset() {
+        this.state = 'closed';
+        this.failures = 0;
+        this.successes = 0;
+        this.lastFailureAt = 0;
+    }
+    /**
+     * Get circuit breaker status for health checks.
+     */
+    getStatus() {
+        return {
+            state: this.getState(),
+            failures: this.failures,
+            successes: this.successes,
+        };
+    }
+}
+export class CircuitOpenError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'CircuitOpenError';
+    }
+}
+//# sourceMappingURL=circuit-breaker.js.map

package/dist/core/circuit-breaker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"circuit-breaker.js","sourceRoot":"","sources":["../../src/core/circuit-breaker.ts"],"names":[],"mappings":"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"}

package/dist/core/conductor.d.ts

@@ -0,0 +1,44 @@
+import { ConfigManager } from './config.js';
+import { DatabaseManager } from './database.js';
+import { PluginManager } from '../plugins/manager.js';
+import { AIManager } from '../ai/manager.js';
+import type { ConductorNotification } from './interfaces.js';
+export interface ConductorOptions {
+    /** Suppress stdout output (required for MCP mode where stdout is protocol). */
+    quiet?: boolean;
+}
+export declare class Conductor {
+    private config;
+    private db;
+    private plugins;
+    private ai;
+    private initialized;
+    private quiet;
+    private proactiveTimer?;
+    private notificationHandler?;
+    /** Prevents overlapping proactive reasoning cycles. */
+    private _cycleRunning;
+    constructor(configPath?: string, options?: ConductorOptions);
+    initialize(): Promise<void>;
+    getConfig(): ConfigManager;
+    getDatabase(): DatabaseManager;
+    isInitialized(): boolean;
+    shutdown(): Promise<void>;
+    getUserInfo(): Promise<unknown>;
+    getTelegramConfig(): Promise<unknown>;
+    getAIConfig(): Promise<unknown>;
+    getPlugins(): Promise<any[]>;
+    getRecentActivity(limit?: number): Promise<any[]>;
+    getPluginsManager(): PluginManager;
+    getAIManager(): AIManager;
+    /** Set a handler for proactive notifications (e.g. from the heartbeat loop). */
+    setNotificationHandler(handler: (notification: ConductorNotification) => Promise<void>): void;
+    /** Send a proactive notification to the user via the registered handler. */
+    notifyUser(notification: ConductorNotification): Promise<void>;
+    /** Start the proactive autonomous loop. */
+    startProactiveMode(intervalMinutes?: number): Promise<void>;
+    stopProactiveMode(): Promise<void>;
+    private gatherContext;
+    runReasoningCycle(): Promise<void>;
+}
+//# sourceMappingURL=conductor.d.ts.map

package/dist/core/conductor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conductor.d.ts","sourceRoot":"","sources":["../../src/core/conductor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAE7D,MAAM,WAAW,gBAAgB;IAC/B,+EAA+E;IAC/E,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,qBAAa,SAAS;IACpB,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,EAAE,CAAkB;IAC5B,OAAO,CAAC,OAAO,CAAgB;IAC/B,OAAO,CAAC,EAAE,CAAY;IACtB,OAAO,CAAC,WAAW,CAAkB;IACrC,OAAO,CAAC,KAAK,CAAU;IACvB,OAAO,CAAC,cAAc,CAAC,CAAiB;IACxC,OAAO,CAAC,mBAAmB,CAAC,CAAyD;IACrF,uDAAuD;IACvD,OAAO,CAAC,aAAa,CAAS;gBAElB,UAAU,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB;IAQrD,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAgBjC,SAAS,IAAI,aAAa;IAI1B,WAAW,IAAI,eAAe;IAI9B,aAAa,IAAI,OAAO;IAIlB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAQzB,WAAW;IAIX,iBAAiB;IAIjB,WAAW;IAIX,UAAU;IAIV,iBAAiB,CAAC,KAAK,GAAE,MAAW;IAI1C,iBAAiB,IAAI,aAAa;IAIlC,YAAY,IAAI,SAAS;IAIzB,gFAAgF;IAChF,sBAAsB,CAAC,OAAO,EAAE,CAAC,YAAY,EAAE,qBAAqB,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI;IAI7F,4EAA4E;IACtE,UAAU,CAAC,YAAY,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC;IAQpE,2CAA2C;IACrC,kBAAkB,CAAC,eAAe,GAAE,MAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAsB/D,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC;YAO1B,aAAa;IA+Cd,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC;CAqDhD"}

package/dist/core/conductor.js

@@ -0,0 +1,200 @@
+import { ConfigManager } from './config.js';
+import { DatabaseManager } from './database.js';
+import { PluginManager } from '../plugins/manager.js';
+import { AIManager } from '../ai/manager.js';
+export class Conductor {
+    config;
+    db;
+    plugins;
+    ai;
+    initialized = false;
+    quiet;
+    proactiveTimer;
+    notificationHandler;
+    /** Prevents overlapping proactive reasoning cycles. */
+    _cycleRunning = false;
+    constructor(configPath, options) {
+        this.config = new ConfigManager(configPath);
+        this.db = new DatabaseManager(this.config.getConfigDir());
+        this.plugins = new PluginManager(this);
+        this.ai = new AIManager(this);
+        this.quiet = options?.quiet ?? false;
+    }
+    async initialize() {
+        if (this.initialized)
+            return;
+        if (!this.quiet) {
+            process.stderr.write('Initializing Conductor...\n');
+        }
+        await this.config.initialize();
+        await this.db.initialize();
+        await this.plugins.loadBuiltins();
+        this.initialized = true;
+        await this.db.logActivity('system', 'conductor_initialized');
+    }
+    getConfig() {
+        return this.config;
+    }
+    getDatabase() {
+        return this.db;
+    }
+    isInitialized() {
+        return this.initialized;
+    }
+    async shutdown() {
+        if (this.initialized) {
+            await this.db.logActivity('system', 'conductor_shutdown');
+            await this.db.close();
+        }
+    }
+    // Quick access methods
+    async getUserInfo() {
+        return this.config.get('user');
+    }
+    async getTelegramConfig() {
+        return this.config.get('telegram');
+    }
+    async getAIConfig() {
+        return this.config.get('ai');
+    }
+    async getPlugins() {
+        return this.db.getPlugins();
+    }
+    async getRecentActivity(limit = 20) {
+        return this.db.getRecentActivity(limit);
+    }
+    getPluginsManager() {
+        return this.plugins;
+    }
+    getAIManager() {
+        return this.ai;
+    }
+    /** Set a handler for proactive notifications (e.g. from the heartbeat loop). */
+    setNotificationHandler(handler) {
+        this.notificationHandler = handler;
+    }
+    /** Send a proactive notification to the user via the registered handler. */
+    async notifyUser(notification) {
+        if (this.notificationHandler) {
+            await this.notificationHandler(notification);
+        }
+        else {
+            process.stderr.write(`  [Proactive] ${notification.title}: ${notification.body}\n`);
+        }
+    }
+    /** Start the proactive autonomous loop. */
+    async startProactiveMode(intervalMinutes = 30) {
+        if (this.proactiveTimer)
+            return;
+        if (!this.quiet) {
+            process.stderr.write(`Starting proactive mode (every ${intervalMinutes}m)...\n`);
+        }
+        // Run once immediately
+        this.runReasoningCycle().catch((err) => {
+            process.stderr.write(`Proactive cycle error: ${err.message}\n`);
+        });
+        this.proactiveTimer = setInterval(() => {
+            this.runReasoningCycle().catch((err) => {
+                process.stderr.write(`Proactive cycle error: ${err.message}\n`);
+            });
+        }, intervalMinutes * 60 * 1000);
+    }
+    async stopProactiveMode() {
+        if (this.proactiveTimer) {
+            clearInterval(this.proactiveTimer);
+            this.proactiveTimer = undefined;
+        }
+    }
+    async gatherContext() {
+        const contextLines = [];
+        // System Info
+        try {
+            const sysPlugin = await this.plugins.getPlugin('system');
+            if (sysPlugin) {
+                const infoTool = sysPlugin.getTools().find((t) => t.name === 'system_info');
+                if (infoTool) {
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    const stats = (await infoTool.handler({}));
+                    contextLines.push(`[SYSTEM] CPU: ${stats.cpu?.load || 'unknown'}%, RAM: ${stats.memory?.usedPercent || 'unknown'}%, Disk: ${stats.disk?.usedPercent || 'unknown'}%`);
+                }
+            }
+        }
+        catch {
+            /* plugin might be disabled */
+        }
+        // Recent Activity
+        const activity = await this.getRecentActivity(5);
+        if (activity.length > 0) {
+            contextLines.push('[RECENT ACTIVITY]');
+            activity.forEach((a) => contextLines.push(`- ${a.timestamp}: ${a.event_type} (${a.service})`));
+        }
+        // enabled plugins
+        const enabled = this.config.get('plugins.enabled') || [];
+        contextLines.push(`[PLUGINS] Enabled: ${enabled.join(', ')}`);
+        // Dynamic context from any enabled plugin that implements getContext()
+        for (const pluginName of enabled) {
+            try {
+                const plugin = await this.plugins.getPlugin(pluginName);
+                if (plugin && typeof plugin.getContext === 'function') {
+                    const ctx = await plugin.getContext();
+                    if (ctx)
+                        contextLines.push(ctx);
+                }
+            }
+            catch {
+                /* ignore — plugin context is best-effort */
+            }
+        }
+        return contextLines.join('\n');
+    }
+    async runReasoningCycle() {
+        if (!this.initialized)
+            return;
+        if (this._cycleRunning) {
+            process.stderr.write('[Proactive] Skipping cycle — previous cycle still running\n');
+            return;
+        }
+        this._cycleRunning = true;
+        await this.db.logActivity('system', 'proactive_cycle_start');
+        try {
+            const context = await this.gatherContext();
+            const provider = await this.ai.getCurrentProvider();
+            if (provider) {
+                const prompt = `You are running your autonomous periodic reasoning cycle.
+Examine the context below. If there is a problem (like high CPU, or important unread emails), use your tools to take action or investigate further. 
+If everything is perfectly normal and no action is required, respond exactly with "No action needed."
+
+CONTEXT:
+${context}`;
+                const systemUserId = 'system-proactive';
+                const agentResponse = await this.ai.handleConversation(systemUserId, prompt);
+                await this.db.logActivity('system', 'proactive_reasoning_complete', agentResponse.text);
+                if (!this.quiet) {
+                    process.stderr.write(`  🤖 [Proactive] ${agentResponse.text}\n`);
+                }
+                if (agentResponse.approvalRequired) {
+                    const { toolName, arguments: args } = agentResponse.approvalRequired;
+                    await this.notifyUser({
+                        title: 'Approval Required',
+                        body: `The AI attempted to use "${toolName}" autonomously. Reply to approve or deny.`,
+                        codeBlock: JSON.stringify(args, null, 2),
+                    });
+                }
+                else if (agentResponse.text && !agentResponse.text.toLowerCase().includes('no action needed')) {
+                    await this.notifyUser({
+                        title: 'Autonomous Action',
+                        body: agentResponse.text,
+                    });
+                }
+            }
+        }
+        catch (err) {
+            process.stderr.write(`  ✗ [Proactive Error] ${err.message}\n`);
+        }
+        finally {
+            this._cycleRunning = false;
+            await this.db.logActivity('system', 'proactive_cycle_end');
+        }
+    }
+}
+//# sourceMappingURL=conductor.js.map