@useconductor/conductor 1.0.0

package/src/core/audit.ts

@@ -0,0 +1,291 @@
+/**
+ * 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 interface AuditEntry {
+  /** ISO 8601 timestamp */
+  timestamp: string;
+  /** Who performed the action: user ID, API key ID, or 'system' */
+  actor: string;
+  /** Action performed: tool_call, config_set, plugin_enable, auth_login, etc. */
+  action: string;
+  /** Resource affected: tool name, config key, plugin name, etc. */
+  resource: string;
+  /** Result: success, failure, denied, timeout */
+  result: 'success' | 'failure' | 'denied' | 'timeout';
+  /** Optional metadata: input, output, error, duration_ms, ip, user_agent */
+  metadata: Record<string, unknown>;
+  /** SHA-256 of previous entry's hash + this entry's content (tamper-evident chain) */
+  hash: string;
+  /** Hash of the previous entry (forms a blockchain-like chain) */
+  previousHash: string;
+}
+
+export class AuditLogger {
+  private logDir: string;
+  private currentFile: string;
+  private lastHash: string;
+  private maxFileSize: number;
+  private buffer: AuditEntry[];
+  private flushTimer: NodeJS.Timeout | null;
+
+  constructor(configDir: string, options?: { maxFileSizeMB?: number; flushIntervalMs?: number }) {
+    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: Omit<AuditEntry, 'hash' | 'previousHash' | 'timestamp'>): Promise<void> {
+    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: AuditEntry = {
+      ...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: string,
+    tool: string,
+    input: unknown,
+    result: 'success' | 'failure' | 'denied' | 'timeout',
+    metadata: Record<string, unknown> = {},
+  ): Promise<void> {
+    await this.log({
+      actor,
+      action: 'tool_call',
+      resource: tool,
+      result,
+      metadata: { input: this.redactSensitive(input), ...metadata },
+    });
+  }
+
+  /**
+   * Convenience: log a config change.
+   */
+  async configChange(actor: string, key: string, oldValue: unknown, newValue: unknown): Promise<void> {
+    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: string,
+    method: string,
+    success: boolean,
+    metadata: Record<string, unknown> = {},
+  ): Promise<void> {
+    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: string,
+    plugin: string,
+    action: 'enable' | 'disable' | 'install' | 'uninstall' | 'update',
+    metadata: Record<string, unknown> = {},
+  ): Promise<void> {
+    await this.log({
+      actor,
+      action: `plugin_${action}`,
+      resource: plugin,
+      result: 'success',
+      metadata,
+    });
+  }
+
+  /**
+   * Query audit logs with filters.
+   */
+  async query(options?: {
+    actor?: string;
+    action?: string;
+    resource?: string;
+    result?: string;
+    since?: string;
+    limit?: number;
+  }): Promise<AuditEntry[]> {
+    const entries: AuditEntry[] = [];
+
+    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) as AuditEntry;
+            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(): Promise<{ valid: boolean; brokenAt?: string }> {
+    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) as AuditEntry;
+
+        // 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(): Promise<void> {
+    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(): Promise<void> {
+    if (this.flushTimer) {
+      clearInterval(this.flushTimer);
+      this.flushTimer = null;
+    }
+    await this.flush();
+  }
+
+  /**
+   * Redact sensitive values from metadata.
+   */
+  private redactSensitive(value: unknown): unknown {
+    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: Record<string, unknown> = {};
+      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;
+  }
+}

package/src/core/circuit-breaker.ts

@@ -0,0 +1,129 @@
+/**
+ * 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;
+}
+
+const DEFAULTS: CircuitBreakerOptions = {
+  failureThreshold: 5,
+  recoveryTimeout: 60_000,
+  successThreshold: 2,
+};
+
+export class CircuitBreaker {
+  private state: CircuitState = 'closed';
+  private failures = 0;
+  private successes = 0;
+  private lastFailureAt = 0;
+  private options: CircuitBreakerOptions;
+
+  constructor(options?: Partial<CircuitBreakerOptions>) {
+    this.options = { ...DEFAULTS, ...options };
+  }
+
+  getState(): CircuitState {
+    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<T>(fn: () => Promise<T>): Promise<T> {
+    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.
+   */
+  private onSuccess(): void {
+    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.
+   */
+  private onFailure(): void {
+    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(): void {
+    this.state = 'closed';
+    this.failures = 0;
+    this.successes = 0;
+    this.lastFailureAt = 0;
+  }
+
+  /**
+   * Get circuit breaker status for health checks.
+   */
+  getStatus(): { state: CircuitState; failures: number; successes: number } {
+    return {
+      state: this.getState(),
+      failures: this.failures,
+      successes: this.successes,
+    };
+  }
+}
+
+export class CircuitOpenError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'CircuitOpenError';
+  }
+}

package/src/core/conductor.ts

@@ -0,0 +1,240 @@
+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 class Conductor {
+  private config: ConfigManager;
+  private db: DatabaseManager;
+  private plugins: PluginManager;
+  private ai: AIManager;
+  private initialized: boolean = false;
+  private quiet: boolean;
+  private proactiveTimer?: NodeJS.Timeout;
+  private notificationHandler?: (notification: ConductorNotification) => Promise<void>;
+  /** Prevents overlapping proactive reasoning cycles. */
+  private _cycleRunning = false;
+
+  constructor(configPath?: string, options?: ConductorOptions) {
+    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(): Promise<void> {
+    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(): ConfigManager {
+    return this.config;
+  }
+
+  getDatabase(): DatabaseManager {
+    return this.db;
+  }
+
+  isInitialized(): boolean {
+    return this.initialized;
+  }
+
+  async shutdown(): Promise<void> {
+    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: number = 20) {
+    return this.db.getRecentActivity(limit);
+  }
+
+  getPluginsManager(): PluginManager {
+    return this.plugins;
+  }
+
+  getAIManager(): AIManager {
+    return this.ai;
+  }
+
+  /** Set a handler for proactive notifications (e.g. from the heartbeat loop). */
+  setNotificationHandler(handler: (notification: ConductorNotification) => Promise<void>): void {
+    this.notificationHandler = handler;
+  }
+
+  /** Send a proactive notification to the user via the registered handler. */
+  async notifyUser(notification: ConductorNotification): Promise<void> {
+    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: number = 30): Promise<void> {
+    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(): Promise<void> {
+    if (this.proactiveTimer) {
+      clearInterval(this.proactiveTimer);
+      this.proactiveTimer = undefined;
+    }
+  }
+
+  private async gatherContext(): Promise<string> {
+    const contextLines: string[] = [];
+
+    // 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({})) as any;
+          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<string[]>('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');
+  }
+
+  public async runReasoningCycle(): Promise<void> {
+    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: any) {
+      process.stderr.write(`  ✗ [Proactive Error] ${err.message}\n`);
+    } finally {
+      this._cycleRunning = false;
+      await this.db.logActivity('system', 'proactive_cycle_end');
+    }
+  }
+}