@hmawla/co-assistant 1.0.0

package/dist/index.js

@@ -0,0 +1,3258 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/core/config.ts
+var config_exports = {};
+__export(config_exports, {
+  AIConfigSchema: () => AIConfigSchema,
+  AppConfigSchema: () => AppConfigSchema,
+  BotConfigSchema: () => BotConfigSchema,
+  ConfigError: () => ConfigError,
+  EnvConfigSchema: () => EnvConfigSchema,
+  PluginConfigSchema: () => PluginConfigSchema,
+  PluginCredentialEntrySchema: () => PluginCredentialEntrySchema,
+  PluginHealthConfigSchema: () => PluginHealthConfigSchema,
+  getConfig: () => getConfig,
+  loadAppConfig: () => loadAppConfig,
+  loadEnvConfig: () => loadEnvConfig,
+  resetConfig: () => resetConfig
+});
+import { z } from "zod";
+import dotenv from "dotenv";
+import { readFileSync, writeFileSync, existsSync } from "fs";
+function formatZodErrors(error) {
+  return error.issues.map((issue) => {
+    const path4 = issue.path.length > 0 ? issue.path.join(".") : "(root)";
+    return `  \u2022 ${path4}: ${issue.message}`;
+  }).join("\n");
+}
+function loadEnvConfig() {
+  const result = dotenv.config();
+  if (result.error) {
+    console.warn(
+      "[config] .env file not found or unreadable \u2014 continuing with existing environment variables"
+    );
+  }
+  const parsed = EnvConfigSchema.safeParse(process.env);
+  if (!parsed.success) {
+    const details = formatZodErrors(parsed.error);
+    throw new ConfigError(
+      `Environment variable validation failed:
+${details}`
+    );
+  }
+  return parsed.data;
+}
+function loadAppConfig(configPath = "./config.json") {
+  let raw = {};
+  if (existsSync(configPath)) {
+    try {
+      const content = readFileSync(configPath, "utf-8");
+      raw = JSON.parse(content);
+    } catch (err) {
+      throw new ConfigError(
+        `Failed to read or parse config file at "${configPath}": ${err.message}`
+      );
+    }
+  } else {
+    const defaults = AppConfigSchema.parse({});
+    try {
+      writeFileSync(configPath, JSON.stringify(defaults, null, 2) + "\n", "utf-8");
+    } catch {
+      console.warn(
+        `[config] Could not write default config to "${configPath}" \u2014 using in-memory defaults`
+      );
+    }
+    raw = defaults;
+  }
+  const parsed = AppConfigSchema.safeParse(raw);
+  if (!parsed.success) {
+    const details = formatZodErrors(parsed.error);
+    throw new ConfigError(
+      `Application config validation failed (${configPath}):
+${details}`
+    );
+  }
+  return parsed.data;
+}
+function getConfig() {
+  if (!cachedConfig) {
+    cachedConfig = {
+      env: loadEnvConfig(),
+      app: loadAppConfig()
+    };
+  }
+  return cachedConfig;
+}
+function resetConfig() {
+  cachedConfig = null;
+}
+var ConfigError, EnvConfigSchema, PluginCredentialEntrySchema, PluginConfigSchema, BotConfigSchema, AIConfigSchema, PluginHealthConfigSchema, AppConfigSchema, cachedConfig;
+var init_config = __esm({
+  "src/core/config.ts"() {
+    "use strict";
+    ConfigError = class extends Error {
+      constructor(message2) {
+        super(message2);
+        this.name = "ConfigError";
+      }
+    };
+    EnvConfigSchema = z.object({
+      TELEGRAM_BOT_TOKEN: z.string().min(1, "TELEGRAM_BOT_TOKEN is required"),
+      TELEGRAM_USER_ID: z.string().min(1, "TELEGRAM_USER_ID is required"),
+      GITHUB_TOKEN: z.string().optional(),
+      LOG_LEVEL: z.enum(["debug", "info", "warn", "error"]).default("info"),
+      DEFAULT_MODEL: z.string().default("gpt-4.1"),
+      HEARTBEAT_INTERVAL_MINUTES: z.string().default("0"),
+      AI_SESSION_POOL_SIZE: z.string().default("3")
+    });
+    PluginCredentialEntrySchema = z.object({
+      key: z.string(),
+      description: z.string(),
+      type: z.string().optional()
+    });
+    PluginConfigSchema = z.object({
+      enabled: z.boolean(),
+      credentials: z.record(z.string(), z.string())
+    });
+    BotConfigSchema = z.object({
+      maxMessageLength: z.number().default(4096),
+      typingIndicator: z.boolean().default(true)
+    });
+    AIConfigSchema = z.object({
+      maxRetries: z.number().default(3),
+      sessionTimeout: z.number().default(36e5)
+    });
+    PluginHealthConfigSchema = z.object({
+      maxFailures: z.number().default(5),
+      checkInterval: z.number().default(6e4)
+    });
+    AppConfigSchema = z.object({
+      plugins: z.record(z.string(), PluginConfigSchema).default({}),
+      bot: BotConfigSchema.default({ maxMessageLength: 4096, typingIndicator: true }),
+      ai: AIConfigSchema.default({ maxRetries: 3, sessionTimeout: 36e5 }),
+      pluginHealth: PluginHealthConfigSchema.default({ maxFailures: 5, checkInterval: 6e4 })
+    });
+    cachedConfig = null;
+  }
+});
+
+// src/storage/migrations/001-initial.ts
+var migration, initial_default;
+var init_initial = __esm({
+  "src/storage/migrations/001-initial.ts"() {
+    "use strict";
+    migration = {
+      id: "001-initial",
+      up: `
+    CREATE TABLE IF NOT EXISTS conversations (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      role TEXT NOT NULL CHECK(role IN ('user', 'assistant', 'system')),
+      content TEXT NOT NULL,
+      model TEXT,
+      created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+    );
+
+    CREATE TABLE IF NOT EXISTS plugin_state (
+      plugin_id TEXT NOT NULL,
+      key TEXT NOT NULL,
+      value TEXT,
+      updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+      PRIMARY KEY (plugin_id, key)
+    );
+
+    CREATE TABLE IF NOT EXISTS preferences (
+      key TEXT PRIMARY KEY,
+      value TEXT NOT NULL,
+      updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
+    );
+
+    CREATE TABLE IF NOT EXISTS plugin_health (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      plugin_id TEXT NOT NULL,
+      status TEXT NOT NULL CHECK(status IN ('ok', 'error', 'disabled')),
+      error_message TEXT,
+      checked_at DATETIME DEFAULT CURRENT_TIMESTAMP
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_conversations_created_at ON conversations(created_at);
+    CREATE INDEX IF NOT EXISTS idx_plugin_health_plugin_id ON plugin_health(plugin_id);
+  `
+    };
+    initial_default = migration;
+  }
+});
+
+// src/storage/database.ts
+import Database from "better-sqlite3";
+import { mkdirSync } from "fs";
+import { dirname } from "path";
+function ensureMigrationsTable(db) {
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS _migrations (
+      id TEXT PRIMARY KEY,
+      applied_at DATETIME DEFAULT CURRENT_TIMESTAMP
+    );
+  `);
+}
+function runMigrations(db) {
+  ensureMigrationsTable(db);
+  const applied = new Set(
+    db.prepare("SELECT id FROM _migrations").all().map(
+      (row) => row.id
+    )
+  );
+  for (const migration2 of MIGRATIONS) {
+    if (applied.has(migration2.id)) continue;
+    const applyMigration = db.transaction(() => {
+      db.exec(migration2.up);
+      db.prepare("INSERT INTO _migrations (id) VALUES (?)").run(migration2.id);
+    });
+    try {
+      applyMigration();
+    } catch (error) {
+      const message2 = error instanceof Error ? error.message : String(error);
+      throw new Error(
+        `Migration "${migration2.id}" failed: ${message2}`
+      );
+    }
+  }
+}
+function getDatabase(dbPath = DEFAULT_DB_PATH) {
+  if (instance) return instance;
+  mkdirSync(dirname(dbPath), { recursive: true });
+  instance = new Database(dbPath);
+  instance.pragma("journal_mode = WAL");
+  runMigrations(instance);
+  return instance;
+}
+function closeDatabase() {
+  if (instance) {
+    instance.close();
+    instance = null;
+  }
+}
+var DEFAULT_DB_PATH, MIGRATIONS, instance;
+var init_database = __esm({
+  "src/storage/database.ts"() {
+    "use strict";
+    init_initial();
+    DEFAULT_DB_PATH = "./data/co-assistant.db";
+    MIGRATIONS = [initial_default];
+    instance = null;
+  }
+});
+
+// src/storage/repositories/plugin-health.ts
+var plugin_health_exports = {};
+__export(plugin_health_exports, {
+  PluginHealthRepository: () => PluginHealthRepository
+});
+var PluginHealthRepository;
+var init_plugin_health = __esm({
+  "src/storage/repositories/plugin-health.ts"() {
+    "use strict";
+    init_database();
+    PluginHealthRepository = class {
+      db;
+      /** Create a new repository backed by the singleton database. */
+      constructor(db) {
+        this.db = db ?? getDatabase();
+      }
+      /**
+       * Record a health-check result for a plugin.
+       *
+       * @param pluginId     - The unique plugin identifier.
+       * @param status       - Health status (`ok`, `error`, or `disabled`).
+       * @param errorMessage - Optional error details.
+       */
+      logHealth(pluginId, status, errorMessage) {
+        this.db.prepare(
+          "INSERT INTO plugin_health (plugin_id, status, error_message) VALUES (?, ?, ?)"
+        ).run(pluginId, status, errorMessage ?? null);
+      }
+      /**
+       * Retrieve the most recent health-check entries for a plugin.
+       *
+       * @param pluginId - The unique plugin identifier.
+       * @param limit    - Maximum number of entries to return (default `10`).
+       * @returns An array of {@link PluginHealthEntry} objects, newest first.
+       */
+      getRecentHealth(pluginId, limit = 10) {
+        return this.db.prepare(
+          "SELECT id, plugin_id, status, error_message, checked_at FROM plugin_health WHERE plugin_id = ? ORDER BY checked_at DESC LIMIT ?"
+        ).all(pluginId, limit);
+      }
+      /**
+       * Count the number of `error` health entries for a plugin within a time window.
+       *
+       * @param pluginId     - The unique plugin identifier.
+       * @param sinceMinutes - Look-back window in minutes (default `60`).
+       * @returns The number of error entries in the window.
+       */
+      getFailureCount(pluginId, sinceMinutes = 60) {
+        const row = this.db.prepare(
+          `SELECT COUNT(*) AS cnt FROM plugin_health
+         WHERE plugin_id = ? AND status = 'error'
+           AND checked_at >= datetime('now', '-' || ? || ' minutes')`
+        ).get(pluginId, sinceMinutes);
+        return row.cnt;
+      }
+    };
+  }
+});
+
+// src/core/app.ts
+import dns from "dns";
+
+// src/core/logger.ts
+import pino from "pino";
+function resolveLogLevel() {
+  const envLevel = process.env.LOG_LEVEL?.toLowerCase();
+  const valid = ["fatal", "error", "warn", "info", "debug", "trace", "silent"];
+  return envLevel && valid.includes(envLevel) ? envLevel : "info";
+}
+function buildLoggerOptions() {
+  const level = resolveLogLevel();
+  const isProduction = process.env.NODE_ENV === "production";
+  const opts = { level };
+  if (!isProduction) {
+    opts.transport = {
+      target: "pino-pretty",
+      options: {
+        colorize: true,
+        translateTime: "SYS:HH:MM:ss",
+        ignore: "pid,hostname"
+      }
+    };
+  }
+  return opts;
+}
+var logger = pino(buildLoggerOptions());
+function createChildLogger(name, meta) {
+  return logger.child({ component: name, ...meta });
+}
+function setLogLevel(level) {
+  logger.level = level;
+}
+
+// src/core/app.ts
+init_config();
+init_database();
+
+// src/storage/repositories/conversation.ts
+init_database();
+var ConversationRepository = class {
+  db;
+  /** Create a new repository backed by the singleton database. */
+  constructor(db) {
+    this.db = db ?? getDatabase();
+  }
+  /**
+   * Insert a new message into the conversations table.
+   *
+   * @param role    - The message role (`user`, `assistant`, or `system`).
+   * @param content - The text content of the message.
+   * @param model   - Optional AI model identifier.
+   */
+  addMessage(role, content, model) {
+    this.db.prepare(
+      "INSERT INTO conversations (role, content, model) VALUES (?, ?, ?)"
+    ).run(role, content, model ?? null);
+  }
+  /**
+   * Retrieve conversation history ordered newest-first.
+   *
+   * @param limit - Maximum number of messages to return (default `50`).
+   * @returns An array of {@link ConversationMessage} objects.
+   */
+  getHistory(limit = 50) {
+    return this.db.prepare(
+      "SELECT id, role, content, model, created_at FROM conversations ORDER BY created_at DESC LIMIT ?"
+    ).all(limit);
+  }
+  /**
+   * Retrieve the most recent messages ordered oldest-first, suitable for
+   * building an AI context window.
+   *
+   * @param limit - Maximum number of messages to return (default `20`).
+   * @returns An array of {@link ConversationMessage} objects in chronological order.
+   */
+  getRecentContext(limit = 20) {
+    return this.db.prepare(
+      `SELECT id, role, content, model, created_at
+         FROM (
+           SELECT id, role, content, model, created_at
+           FROM conversations
+           ORDER BY created_at DESC
+           LIMIT ?
+         ) sub
+         ORDER BY created_at ASC`
+    ).all(limit);
+  }
+  /**
+   * Delete all conversation messages.
+   */
+  clear() {
+    this.db.prepare("DELETE FROM conversations").run();
+  }
+  /**
+   * Return the total number of stored conversation messages.
+   */
+  count() {
+    const row = this.db.prepare("SELECT COUNT(*) AS cnt FROM conversations").get();
+    return row.cnt;
+  }
+};
+
+// src/storage/repositories/preferences.ts
+init_database();
+var PreferencesRepository = class {
+  db;
+  /** Create a new repository backed by the singleton database. */
+  constructor(db) {
+    this.db = db ?? getDatabase();
+  }
+  /**
+   * Retrieve a preference value by key.
+   *
+   * @param key - The preference key.
+   * @returns The stored value, or `null` if not found.
+   */
+  get(key) {
+    const row = this.db.prepare("SELECT value FROM preferences WHERE key = ?").get(key);
+    return row?.value ?? null;
+  }
+  /**
+   * Insert or update a preference value.
+   *
+   * @param key   - The preference key.
+   * @param value - The value to store.
+   */
+  set(key, value) {
+    this.db.prepare(
+      `INSERT INTO preferences (key, value, updated_at)
+         VALUES (?, ?, CURRENT_TIMESTAMP)
+         ON CONFLICT(key) DO UPDATE SET value = excluded.value, updated_at = CURRENT_TIMESTAMP`
+    ).run(key, value);
+  }
+  /**
+   * Retrieve all preferences as a plain object.
+   *
+   * @returns A record mapping each preference key to its value.
+   */
+  getAll() {
+    const rows = this.db.prepare("SELECT key, value FROM preferences").all();
+    const result = {};
+    for (const row of rows) {
+      result[row.key] = row.value;
+    }
+    return result;
+  }
+  /**
+   * Delete a single preference by key.
+   *
+   * @param key - The preference key to remove.
+   */
+  delete(key) {
+    this.db.prepare("DELETE FROM preferences WHERE key = ?").run(key);
+  }
+};
+
+// src/storage/repositories/plugin-state.ts
+init_database();
+var PluginStateRepository = class {
+  db;
+  /** Create a new repository backed by the singleton database. */
+  constructor(db) {
+    this.db = db ?? getDatabase();
+  }
+  /**
+   * Retrieve a single value for a given plugin and key.
+   *
+   * @param pluginId - The unique plugin identifier.
+   * @param key      - The state key.
+   * @returns The stored value, or `null` if not found.
+   */
+  get(pluginId, key) {
+    const row = this.db.prepare("SELECT value FROM plugin_state WHERE plugin_id = ? AND key = ?").get(pluginId, key);
+    return row?.value ?? null;
+  }
+  /**
+   * Insert or update a state value for a plugin.
+   *
+   * @param pluginId - The unique plugin identifier.
+   * @param key      - The state key.
+   * @param value    - The value to store.
+   */
+  set(pluginId, key, value) {
+    this.db.prepare(
+      `INSERT INTO plugin_state (plugin_id, key, value, updated_at)
+         VALUES (?, ?, ?, CURRENT_TIMESTAMP)
+         ON CONFLICT(plugin_id, key) DO UPDATE SET value = excluded.value, updated_at = CURRENT_TIMESTAMP`
+    ).run(pluginId, key, value);
+  }
+  /**
+   * Retrieve all key/value pairs for a plugin.
+   *
+   * @param pluginId - The unique plugin identifier.
+   * @returns A plain object mapping keys to their string values.
+   */
+  getAll(pluginId) {
+    const rows = this.db.prepare("SELECT key, value FROM plugin_state WHERE plugin_id = ?").all(pluginId);
+    const result = {};
+    for (const row of rows) {
+      result[row.key] = row.value;
+    }
+    return result;
+  }
+  /**
+   * Delete a single state key for a plugin.
+   *
+   * @param pluginId - The unique plugin identifier.
+   * @param key      - The state key to remove.
+   */
+  delete(pluginId, key) {
+    this.db.prepare("DELETE FROM plugin_state WHERE plugin_id = ? AND key = ?").run(pluginId, key);
+  }
+  /**
+   * Remove all stored state for a specific plugin.
+   *
+   * @param pluginId - The unique plugin identifier.
+   */
+  clearPlugin(pluginId) {
+    this.db.prepare("DELETE FROM plugin_state WHERE plugin_id = ?").run(pluginId);
+  }
+};
+
+// src/ai/models.ts
+init_config();
+var DEFAULT_MODELS = [
+  // OpenAI — Premium (3x)
+  { id: "gpt-5", name: "GPT-5", description: "OpenAI GPT-5 (premium, 3x)", provider: "openai" },
+  { id: "o3", name: "o3", description: "OpenAI o3 reasoning (premium, 3x)", provider: "openai" },
+  // OpenAI — Standard (1x)
+  { id: "gpt-4.1", name: "GPT-4.1", description: "OpenAI GPT-4.1 (1x)", provider: "openai" },
+  { id: "gpt-4o", name: "GPT-4o", description: "OpenAI GPT-4o multimodal (1x)", provider: "openai" },
+  { id: "o4-mini", name: "o4 Mini", description: "OpenAI o4-mini reasoning (1x)", provider: "openai" },
+  // OpenAI — Low (0.33x)
+  { id: "gpt-4o-mini", name: "GPT-4o Mini", description: "OpenAI GPT-4o Mini (0.33x)", provider: "openai" },
+  { id: "gpt-4.1-mini", name: "GPT-4.1 Mini", description: "OpenAI GPT-4.1 Mini (0.33x)", provider: "openai" },
+  { id: "gpt-5-mini", name: "GPT-5 Mini", description: "OpenAI GPT-5 Mini (0.33x)", provider: "openai" },
+  { id: "o3-mini", name: "o3 Mini", description: "OpenAI o3-mini reasoning (0.33x)", provider: "openai" },
+  // OpenAI — Nano (0x)
+  { id: "gpt-4.1-nano", name: "GPT-4.1 Nano", description: "OpenAI GPT-4.1 Nano (0x)", provider: "openai" },
+  // Anthropic — Premium (3x)
+  { id: "claude-opus-4", name: "Claude Opus 4", description: "Anthropic Claude Opus 4 (premium, 3x)", provider: "anthropic" },
+  // Anthropic — Standard (1x)
+  { id: "claude-sonnet-4", name: "Claude Sonnet 4", description: "Anthropic Claude Sonnet 4 (1x)", provider: "anthropic" },
+  // Anthropic — Low (0.33x)
+  { id: "claude-haiku-4.5", name: "Claude Haiku 4.5", description: "Anthropic Claude Haiku 4.5 (0.33x)", provider: "anthropic" }
+];
+var PREF_KEY = "current_model";
+var ModelRegistry = class {
+  models;
+  preferences;
+  logger;
+  /**
+   * @param preferences - Repository used to persist the selected model.
+   */
+  constructor(preferences) {
+    this.models = [...DEFAULT_MODELS];
+    this.preferences = preferences;
+    this.logger = createChildLogger("ai:models");
+    this.logger.debug({ count: this.models.length }, "Model registry initialised");
+  }
+  /**
+   * Return every model currently registered (built-in + custom).
+   *
+   * @returns A shallow copy of the model list.
+   */
+  getAvailableModels() {
+    return [...this.models];
+  }
+  /**
+   * Look up a single model by its identifier.
+   *
+   * @param modelId - Case-sensitive model identifier.
+   * @returns The matching {@link ModelInfo}, or `undefined` when not found.
+   */
+  getModel(modelId) {
+    return this.models.find((m) => m.id === modelId);
+  }
+  /**
+   * Resolve the currently active model identifier.
+   *
+   * Resolution order:
+   * 1. Persisted preference (`current_model` key)
+   * 2. `DEFAULT_MODEL` from the environment configuration
+   *
+   * @returns The model identifier string.
+   */
+  getCurrentModelId() {
+    const persisted = this.preferences.get(PREF_KEY);
+    if (persisted) {
+      this.logger.debug({ modelId: persisted }, "Current model resolved from preferences");
+      return persisted;
+    }
+    try {
+      const defaultModel = getConfig().env.DEFAULT_MODEL;
+      this.logger.debug({ modelId: defaultModel }, "Current model resolved from env default");
+      return defaultModel;
+    } catch {
+      const fallback = "gpt-4.1";
+      this.logger.debug({ modelId: fallback }, "Current model resolved from hardcoded fallback");
+      return fallback;
+    }
+  }
+  /**
+   * Select a model as the active model and persist the choice.
+   *
+   * Unknown model IDs are **allowed** (the Copilot SDK may support models
+   * not present in our registry) but a warning is logged so operators can
+   * spot potential typos.
+   *
+   * @param modelId - The identifier of the model to activate.
+   */
+  setCurrentModel(modelId) {
+    if (!this.isValidModel(modelId)) {
+      this.logger.warn(
+        { modelId },
+        "Setting model that is not in the registry \u2014 it may still be valid for the provider"
+      );
+    }
+    this.preferences.set(PREF_KEY, modelId);
+    this.logger.info({ modelId }, "Current model updated");
+  }
+  /**
+   * Check whether a model identifier corresponds to a registered model.
+   *
+   * @param modelId - The identifier to validate.
+   * @returns `true` when the model exists in the registry.
+   */
+  isValidModel(modelId) {
+    return this.models.some((m) => m.id === modelId);
+  }
+  /**
+   * Register a custom model at runtime (e.g. for BYOK scenarios).
+   *
+   * If a model with the same `id` already exists it will be replaced.
+   *
+   * @param model - The {@link ModelInfo} to add.
+   */
+  addModel(model) {
+    const idx = this.models.findIndex((m) => m.id === model.id);
+    if (idx !== -1) {
+      this.models[idx] = model;
+      this.logger.info({ modelId: model.id }, "Existing model replaced in registry");
+    } else {
+      this.models.push(model);
+      this.logger.info({ modelId: model.id }, "Custom model added to registry");
+    }
+  }
+  /**
+   * Remove a model from the registry.
+   *
+   * @param modelId - The identifier of the model to remove.
+   * @returns `true` if the model was found and removed, `false` otherwise.
+   */
+  removeModel(modelId) {
+    const idx = this.models.findIndex((m) => m.id === modelId);
+    if (idx === -1) {
+      this.logger.warn({ modelId }, "Attempted to remove unknown model");
+      return false;
+    }
+    this.models.splice(idx, 1);
+    this.logger.info({ modelId }, "Model removed from registry");
+    return true;
+  }
+};
+function createModelRegistry(preferences) {
+  return new ModelRegistry(preferences);
+}
+
+// src/ai/client.ts
+import { CopilotClient } from "@github/copilot-sdk";
+
+// src/core/errors.ts
+var CoAssistantError = class extends Error {
+  /** Machine-readable error code. */
+  code;
+  /** Optional structured context for debugging. */
+  context;
+  constructor(message2, code, context) {
+    super(message2);
+    this.name = this.constructor.name;
+    this.code = code;
+    this.context = context;
+    Object.setPrototypeOf(this, new.target.prototype);
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+};
+var PluginError = class _PluginError extends CoAssistantError {
+  /** Identifier of the plugin that produced this error. */
+  pluginId;
+  constructor(message2, code, pluginId, context) {
+    super(message2, code, { ...context, pluginId });
+    this.pluginId = pluginId;
+  }
+  /** Plugin initialisation failed. */
+  static initFailed(pluginId, reason) {
+    return new _PluginError(
+      `Plugin "${pluginId}" failed to initialise: ${reason}`,
+      "PLUGIN_INIT_FAILED",
+      pluginId,
+      { reason }
+    );
+  }
+  /** A tool exposed by the plugin failed during execution. */
+  static toolFailed(pluginId, toolName, reason) {
+    return new _PluginError(
+      `Plugin "${pluginId}" tool "${toolName}" failed: ${reason}`,
+      "PLUGIN_TOOL_FAILED",
+      pluginId,
+      { toolName, reason }
+    );
+  }
+  /** Required credentials for the plugin are missing. */
+  static credentialsMissing(pluginId, keys) {
+    return new _PluginError(
+      `Plugin "${pluginId}" is missing required credentials: ${keys.join(", ")}`,
+      "PLUGIN_CREDENTIALS_MISSING",
+      pluginId,
+      { keys }
+    );
+  }
+  /** Plugin health check did not pass. */
+  static healthCheckFailed(pluginId, reason) {
+    return new _PluginError(
+      `Plugin "${pluginId}" health check failed: ${reason}`,
+      "PLUGIN_HEALTH_CHECK_FAILED",
+      pluginId,
+      { reason }
+    );
+  }
+  /** Plugin is disabled and cannot be used. */
+  static disabled(pluginId, reason) {
+    return new _PluginError(
+      `Plugin "${pluginId}" is disabled: ${reason}`,
+      "PLUGIN_DISABLED",
+      pluginId,
+      { reason }
+    );
+  }
+};
+var AIError = class _AIError extends CoAssistantError {
+  constructor(message2, code, context) {
+    super(message2, code, context);
+  }
+  /** The AI client failed to start. */
+  static clientStartFailed(reason) {
+    return new _AIError(
+      `AI client failed to start: ${reason}`,
+      "AI_CLIENT_START_FAILED",
+      { reason }
+    );
+  }
+  /** A new AI session could not be created. */
+  static sessionCreateFailed(reason) {
+    return new _AIError(
+      `Failed to create AI session: ${reason}`,
+      "AI_SESSION_CREATE_FAILED",
+      { reason }
+    );
+  }
+  /** The requested model was not found or is unavailable. */
+  static modelNotFound(model) {
+    return new _AIError(
+      `AI model not found: ${model}`,
+      "AI_MODEL_NOT_FOUND",
+      { model }
+    );
+  }
+  /** Sending a message to the AI failed. */
+  static sendFailed(reason) {
+    return new _AIError(
+      `Failed to send message to AI: ${reason}`,
+      "AI_SEND_FAILED",
+      { reason }
+    );
+  }
+};
+
+// src/ai/client.ts
+var logger2 = createChildLogger("ai:client");
+var CopilotClientWrapper = class {
+  client = null;
+  isStarted = false;
+  /** Start the Copilot client. Must be called before creating sessions. */
+  async start() {
+    if (this.isStarted) {
+      logger2.warn("Client already started \u2014 skipping");
+      return;
+    }
+    try {
+      logger2.info("Starting Copilot client\u2026");
+      this.client = new CopilotClient();
+      await this.client.start();
+      this.isStarted = true;
+      logger2.info("Copilot client started successfully");
+    } catch (error) {
+      this.client = null;
+      this.isStarted = false;
+      const reason = error instanceof Error ? error.message : String(error);
+      logger2.error({ err: error }, "Failed to start Copilot client");
+      throw AIError.clientStartFailed(reason);
+    }
+  }
+  /** Stop the Copilot client gracefully. */
+  async stop() {
+    if (!this.isStarted || !this.client) {
+      logger2.debug("Client not running \u2014 nothing to stop");
+      return;
+    }
+    try {
+      logger2.info("Stopping Copilot client\u2026");
+      await this.client.stop();
+      logger2.info("Copilot client stopped");
+    } catch (error) {
+      logger2.error({ err: error }, "Error while stopping Copilot client (ignored)");
+    } finally {
+      this.client = null;
+      this.isStarted = false;
+    }
+  }
+  /**
+   * Get the underlying {@link CopilotClient}.
+   * @throws {AIError} If the client has not been started.
+   */
+  getClient() {
+    if (!this.isStarted || !this.client) {
+      throw AIError.clientStartFailed("Client not started");
+    }
+    return this.client;
+  }
+  /** Check if the client is running. */
+  isRunning() {
+    return this.isStarted;
+  }
+  /** Restart the client (stop then start). */
+  async restart() {
+    logger2.info("Restarting Copilot client\u2026");
+    await this.stop();
+    await this.start();
+  }
+};
+var copilotClient = new CopilotClientWrapper();
+
+// src/ai/session.ts
+import { approveAll, defineTool } from "@github/copilot-sdk";
+import { readFileSync as readFileSync2, existsSync as existsSync2 } from "fs";
+import path from "path";
+var logger3 = createChildLogger("ai:session");
+function convertTools(tools) {
+  return tools.map(
+    (t) => defineTool(t.name, {
+      description: t.description,
+      parameters: t.parameters,
+      handler: t.handler
+    })
+  );
+}
+var SessionManager = class _SessionManager {
+  // 5 minutes
+  constructor(clientWrapper) {
+    this.clientWrapper = clientWrapper;
+    this.logger = logger3;
+    this.personalityPath = path.join(process.cwd(), "personality.md");
+    this.userProfilePath = path.join(process.cwd(), "user.md");
+  }
+  clientWrapper;
+  /** Pool of parallel Copilot sessions. */
+  pool = [];
+  /** Configured pool size — how many parallel sessions to maintain. */
+  poolSize = 3;
+  currentModel = "";
+  tools = [];
+  logger;
+  /**
+   * Cached personality prompt loaded from `personality.md`.
+   * Reloaded from disk on each message so edits take effect immediately.
+   */
+  personalityPath;
+  /** Path to the user profile loaded from `user.md`. */
+  userProfilePath;
+  /**
+   * Callers blocked waiting for a free session.
+   * Drained FIFO when a session is released.
+   */
+  waiters = [];
+  /** Maximum time (ms) a caller will wait in the queue before giving up. */
+  static ACQUIRE_TIMEOUT_MS = 3e5;
+  /**
+   * Read a markdown context file from disk.
+   *
+   * Reads fresh on each call so edits take effect without restart.
+   * Returns an empty string if the file is missing or unreadable.
+   */
+  loadContextFile(filePath, label) {
+    try {
+      if (!existsSync2(filePath)) return "";
+      return readFileSync2(filePath, "utf-8").trim();
+    } catch {
+      this.logger.warn(`Could not read ${label} \u2014 skipping`);
+      return "";
+    }
+  }
+  /**
+   * Wrap a user prompt with system-level context (personality + user profile).
+   *
+   * Both files are read fresh from disk so edits take effect immediately.
+   * The personality defines *how* the assistant behaves; the user profile
+   * tells it *who* it's talking to.
+   */
+  applySystemContext(prompt) {
+    const personality = this.loadContextFile(this.personalityPath, "personality.md");
+    const userProfile = this.loadContextFile(this.userProfilePath, "user.md");
+    const parts = [];
+    if (personality) parts.push(personality);
+    if (userProfile) parts.push(userProfile);
+    if (parts.length === 0) return prompt;
+    return `<system>
+${parts.join("\n\n---\n\n")}
+</system>
+
+${prompt}`;
+  }
+  // -----------------------------------------------------------------------
+  // Pool management (private)
+  // -----------------------------------------------------------------------
+  /**
+   * Acquire a free session from the pool.
+   *
+   * Prefers the lowest-index free session so that sequential interactions
+   * (e.g. back-to-back user messages) naturally reuse the same session and
+   * keep their conversation context. If all sessions are busy, the caller
+   * blocks until one is released or the acquire timeout fires.
+   */
+  acquire() {
+    const free = this.pool.find((s) => !s.busy);
+    if (free) {
+      free.busy = true;
+      return Promise.resolve(free);
+    }
+    return new Promise((resolve, reject) => {
+      const waiter = { resolve, reject };
+      const timer = setTimeout(() => {
+        const idx = this.waiters.indexOf(waiter);
+        if (idx >= 0) this.waiters.splice(idx, 1);
+        reject(AIError.sendFailed("Timed out waiting for a free AI session"));
+      }, _SessionManager.ACQUIRE_TIMEOUT_MS);
+      waiter.resolve = (ps) => {
+        clearTimeout(timer);
+        resolve(ps);
+      };
+      this.waiters.push(waiter);
+    });
+  }
+  /**
+   * Release a session back to the pool.
+   *
+   * If callers are queued waiting for a session, the session is handed
+   * directly to the next waiter (stays marked as busy) instead of being
+   * returned to the idle pool — this avoids an unnecessary acquire cycle.
+   */
+  release(ps) {
+    if (this.waiters.length > 0) {
+      const waiter = this.waiters.shift();
+      waiter.resolve(ps);
+    } else {
+      ps.busy = false;
+    }
+  }
+  // -----------------------------------------------------------------------
+  // Session creation
+  // -----------------------------------------------------------------------
+  /**
+   * Create a pool of Copilot sessions with the specified model and tools.
+   *
+   * Sessions are created in parallel for faster startup. If any session
+   * fails to create, all successful ones are cleaned up and the error
+   * propagates.
+   *
+   * @param model    - Model identifier (e.g. `"gpt-5"`, `"claude-sonnet-4.5"`).
+   * @param tools    - Optional array of tool definitions to register.
+   * @param poolSize - Number of parallel sessions (default: 3).
+   * @throws {AIError} If session creation fails.
+   */
+  async createSession(model, tools, poolSize) {
+    if (this.pool.length > 0) {
+      this.logger.warn("Session pool already exists \u2014 closing before re-creating");
+      await this.closeSession();
+    }
+    if (tools) this.tools = tools;
+    if (poolSize !== void 0 && poolSize > 0) this.poolSize = poolSize;
+    try {
+      const client = this.clientWrapper.getClient();
+      const sdkTools = convertTools(this.tools);
+      this.logger.info(
+        { model, toolCount: sdkTools.length, poolSize: this.poolSize },
+        "Creating session pool"
+      );
+      const results = await Promise.allSettled(
+        Array.from({ length: this.poolSize }, async (_, i) => {
+          const session = await client.createSession({
+            model,
+            tools: sdkTools.length > 0 ? sdkTools : void 0,
+            onPermissionRequest: approveAll
+          });
+          this.logger.debug({ index: i }, "Pool session created");
+          return { session, busy: false, index: i };
+        })
+      );
+      const created = [];
+      const errors = [];
+      for (const r of results) {
+        if (r.status === "fulfilled") {
+          created.push(r.value);
+        } else {
+          errors.push(r.reason);
+        }
+      }
+      if (errors.length > 0) {
+        for (const ps of created) {
+          try {
+            await ps.session.disconnect();
+          } catch {
+          }
+        }
+        const first = errors[0] instanceof Error ? errors[0].message : String(errors[0]);
+        throw new Error(`${errors.length}/${this.poolSize} sessions failed: ${first}`);
+      }
+      this.pool = created;
+      this.currentModel = model;
+      this.logger.info({ model, poolSize: this.poolSize }, "Session pool ready");
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error);
+      this.logger.error({ err: error, model }, "Failed to create session pool");
+      throw AIError.sessionCreateFailed(reason);
+    }
+  }
+  // -----------------------------------------------------------------------
+  // Messaging
+  // -----------------------------------------------------------------------
+  /**
+   * Send a prompt and wait for the complete assistant response.
+   *
+   * Acquires a free session from the pool, sends the prompt via
+   * `sendAndWait`, and releases the session when done. Multiple callers
+   * can run in parallel (up to `poolSize`). If all sessions are busy,
+   * the caller blocks until one frees up.
+   *
+   * @param prompt  - The user message to send.
+   * @param timeout - Timeout in ms (default: 300 000 = 5 min). Complex prompts
+   *                  involving multiple tool calls (e.g. heartbeats) can take
+   *                  longer than the SDK's default 60 s.
+   * @returns The assistant's full response content.
+   * @throws {AIError} If no session pool is active or the send fails.
+   */
+  async sendMessage(prompt, timeout = 3e5) {
+    this.ensureSession();
+    const fullPrompt = this.applySystemContext(prompt);
+    const ps = await this.acquire();
+    try {
+      this.logger.debug(
+        { promptLength: fullPrompt.length, timeout, session: ps.index },
+        "Sending message (blocking)"
+      );
+      const response = await ps.session.sendAndWait({ prompt: fullPrompt }, timeout);
+      const content = response?.data?.content ?? "";
+      this.logger.debug(
+        { responseLength: content.length, session: ps.index },
+        "Received response"
+      );
+      return content;
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error);
+      this.logger.error({ err: error, session: ps.index }, "sendMessage failed");
+      throw AIError.sendFailed(reason);
+    } finally {
+      this.release(ps);
+    }
+  }
+  /**
+   * Send a prompt with streaming — invokes `onChunk` for each incremental
+   * delta and returns the full accumulated response when the session goes idle.
+   *
+   * Acquires a pooled session for the duration of the streaming call.
+   *
+   * @param prompt  - The user message to send.
+   * @param onChunk - Callback invoked with each streaming text delta.
+   * @returns The full accumulated response string.
+   * @throws {AIError} If no session pool is active or the send fails.
+   */
+  async sendMessageStreaming(prompt, onChunk) {
+    this.ensureSession();
+    const fullPrompt = this.applySystemContext(prompt);
+    const ps = await this.acquire();
+    try {
+      this.logger.debug(
+        { promptLength: fullPrompt.length, session: ps.index },
+        "Sending message (streaming)"
+      );
+      let accumulated = "";
+      const done = new Promise((resolve, reject) => {
+        ps.session.on("assistant.message_delta", (event) => {
+          const delta = event.data.deltaContent ?? "";
+          if (delta) {
+            accumulated += delta;
+            onChunk(delta);
+          }
+        });
+        ps.session.on("assistant.message", (event) => {
+          const content = event.data.content ?? "";
+          if (content) {
+            accumulated = content;
+          }
+        });
+        ps.session.on("session.idle", () => {
+          resolve(accumulated);
+        });
+        ps.session.on("error", (err) => {
+          reject(err);
+        });
+      });
+      await ps.session.send({ prompt: fullPrompt });
+      const result = await done;
+      this.logger.debug(
+        { responseLength: result.length, session: ps.index },
+        "Streaming response complete"
+      );
+      return result;
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error);
+      this.logger.error({ err: error, session: ps.index }, "sendMessageStreaming failed");
+      throw AIError.sendFailed(reason);
+    } finally {
+      this.release(ps);
+    }
+  }
+  // -----------------------------------------------------------------------
+  // Model / tool management
+  // -----------------------------------------------------------------------
+  /**
+   * Switch to a different model. Closes the entire pool and creates a new
+   * one with the same tool set and pool size.
+   *
+   * @param model - The new model identifier.
+   * @throws {AIError} If pool recreation fails.
+   */
+  async switchModel(model) {
+    this.logger.info({ from: this.currentModel, to: model }, "Switching model");
+    await this.closeSession();
+    await this.createSession(model, this.tools);
+  }
+  /**
+   * Replace the registered tool set. The pool must be rebuilt because the
+   * Copilot SDK binds tools at session creation time.
+   *
+   * @param tools - New array of tool definitions.
+   * @throws {AIError} If pool recreation fails.
+   */
+  async updateTools(tools) {
+    this.logger.info({ toolCount: tools.length }, "Updating tools (pool rebuild required)");
+    this.tools = tools;
+    if (this.pool.length > 0) {
+      await this.closeSession();
+      await this.createSession(this.currentModel, this.tools);
+    }
+  }
+  // -----------------------------------------------------------------------
+  // Session lifecycle
+  // -----------------------------------------------------------------------
+  /**
+   * Close all sessions in the pool and release resources.
+   *
+   * Any callers blocked in {@link acquire} are rejected with an error.
+   * Safe to call even when the pool is empty (no-op).
+   */
+  async closeSession() {
+    if (this.pool.length === 0) {
+      this.logger.debug("No active sessions to close");
+      return;
+    }
+    for (const waiter of this.waiters) {
+      waiter.reject(AIError.sessionCreateFailed("Session pool is closing"));
+    }
+    this.waiters = [];
+    this.logger.info({ poolSize: this.pool.length }, "Closing session pool");
+    await Promise.allSettled(
+      this.pool.map(async (ps) => {
+        try {
+          await ps.session.disconnect();
+        } catch (err) {
+          this.logger.error({ err, index: ps.index }, "Error closing pool session (ignored)");
+        }
+      })
+    );
+    this.pool = [];
+    this.logger.info("Session pool closed");
+  }
+  /**
+   * Get the identifier of the model used by the current (or most recent) pool.
+   */
+  getCurrentModel() {
+    return this.currentModel;
+  }
+  /**
+   * Check whether the session pool has at least one session.
+   */
+  isActive() {
+    return this.pool.length > 0;
+  }
+  /**
+   * Number of sessions not currently processing a message.
+   * Useful for the Telegram handler to decide whether to show a "queued" notice.
+   */
+  getAvailableCount() {
+    return this.pool.filter((s) => !s.busy).length;
+  }
+  /**
+   * Total number of sessions in the pool.
+   */
+  getPoolSize() {
+    return this.poolSize;
+  }
+  // -----------------------------------------------------------------------
+  // Internal helpers
+  // -----------------------------------------------------------------------
+  /**
+   * Guard that throws if the pool is empty.
+   * @throws {AIError} When called without an active pool.
+   */
+  ensureSession() {
+    if (this.pool.length === 0) {
+      throw AIError.sessionCreateFailed("No active sessions \u2014 call createSession() first");
+    }
+  }
+};
+var sessionManager = new SessionManager(copilotClient);
+
+// src/plugins/registry.ts
+import path2 from "path";
+import {
+  existsSync as existsSync3,
+  mkdirSync as mkdirSync2,
+  readdirSync,
+  readFileSync as readFileSync3,
+  statSync,
+  writeFileSync as writeFileSync2
+} from "fs";
+
+// src/plugins/types.ts
+import { z as z2 } from "zod";
+var CredentialRequirementSchema = z2.object({
+  /** Credential key used to look up the value at runtime. */
+  key: z2.string(),
+  /** Human-readable explanation of what this credential is for. */
+  description: z2.string(),
+  /**
+   * Type hint for the credential.
+   * - `"text"` — plain text secret (default)
+   * - `"oauth"` — OAuth token / flow
+   * - `"apikey"` — API key
+   */
+  type: z2.enum(["text", "oauth", "apikey"]).default("text")
+});
+var PluginManifestSchema = z2.object({
+  /**
+   * Unique plugin identifier.
+   * Must be kebab-case (`a-z`, `0-9`, and `-` only).
+   */
+  id: z2.string().regex(/^[a-z0-9-]+$/, "Plugin ID must be kebab-case"),
+  /** Human-readable display name. */
+  name: z2.string().min(1),
+  /**
+   * Semantic version string (e.g. `"1.2.3"`).
+   * Must follow strict `MAJOR.MINOR.PATCH` format.
+   */
+  version: z2.string().regex(/^\d+\.\d+\.\d+$/, "Must be semver"),
+  /** Short description of what this plugin does. */
+  description: z2.string(),
+  /** Optional author or organisation name. */
+  author: z2.string().optional(),
+  /**
+   * Credentials the plugin requires to operate.
+   * The loader will verify all required credentials are present before
+   * calling `initialize()`.
+   */
+  requiredCredentials: z2.array(CredentialRequirementSchema).default([]),
+  /**
+   * IDs of other plugins this plugin depends on.
+   * Dependencies are loaded and initialised first.
+   */
+  dependencies: z2.array(z2.string()).default([])
+});
+
+// src/plugins/registry.ts
+init_config();
+var MANIFEST_FILENAME = "plugin.json";
+var CONFIG_PATH = "./config.json";
+var PluginRegistry = class {
+  /**
+   * @param pluginsDir - Absolute or relative path to the directory that
+   *   contains plugin subdirectories.
+   */
+  constructor(pluginsDir) {
+    this.pluginsDir = pluginsDir;
+    this.logger = createChildLogger("plugins:registry");
+  }
+  pluginsDir;
+  /** Validated manifests keyed by plugin ID. */
+  manifests = /* @__PURE__ */ new Map();
+  /** Set of currently-enabled plugin IDs. */
+  enabledPlugins = /* @__PURE__ */ new Set();
+  /** Namespaced logger for registry operations. */
+  logger;
+  // -----------------------------------------------------------------------
+  // Discovery
+  // -----------------------------------------------------------------------
+  /**
+   * Scan the plugins directory and discover all available plugins.
+   *
+   * For every subdirectory that contains a valid `plugin.json` the manifest
+   * is parsed, validated with {@link PluginManifestSchema}, and stored.
+   * Invalid or missing manifests are logged as warnings and skipped — they
+   * never crash the application.
+   *
+   * After discovery the enabled state for each plugin is loaded from the
+   * application config (`config.json → app.plugins[id].enabled`).
+   *
+   * @returns Array of all successfully validated {@link PluginManifest}s.
+   */
+  async discoverPlugins() {
+    this.manifests.clear();
+    this.enabledPlugins.clear();
+    if (!existsSync3(this.pluginsDir)) {
+      this.logger.info(
+        { pluginsDir: this.pluginsDir },
+        "Plugins directory does not exist \u2014 creating it"
+      );
+      mkdirSync2(this.pluginsDir, { recursive: true });
+      return [];
+    }
+    const entries = readdirSync(this.pluginsDir);
+    for (const entry of entries) {
+      const entryPath = path2.join(this.pluginsDir, entry);
+      if (!statSync(entryPath).isDirectory()) {
+        continue;
+      }
+      const manifestPath = path2.join(entryPath, MANIFEST_FILENAME);
+      if (!existsSync3(manifestPath)) {
+        this.logger.warn(
+          { dir: entry },
+          `Skipping "${entry}": no ${MANIFEST_FILENAME} found`
+        );
+        continue;
+      }
+      let raw;
+      try {
+        const content = readFileSync3(manifestPath, "utf-8");
+        raw = JSON.parse(content);
+      } catch (err) {
+        this.logger.warn(
+          { dir: entry, error: err.message },
+          `Skipping "${entry}": failed to read or parse ${MANIFEST_FILENAME}`
+        );
+        continue;
+      }
+      const result = PluginManifestSchema.safeParse(raw);
+      if (!result.success) {
+        const issues = result.error.issues.map((i) => `  \u2022 ${i.path.join(".")}: ${i.message}`).join("\n");
+        this.logger.warn(
+          { dir: entry },
+          `Skipping "${entry}": manifest validation failed:
+${issues}`
+        );
+        continue;
+      }
+      const manifest = result.data;
+      this.manifests.set(manifest.id, manifest);
+      this.logger.info(
+        { pluginId: manifest.id, version: manifest.version },
+        `Discovered plugin "${manifest.name}"`
+      );
+    }
+    this.loadEnabledState();
+    return this.getManifests();
+  }
+  // -----------------------------------------------------------------------
+  // Manifest accessors
+  // -----------------------------------------------------------------------
+  /**
+   * Get all discovered plugin manifests.
+   *
+   * @returns A shallow copy of the manifests array.
+   */
+  getManifests() {
+    return Array.from(this.manifests.values());
+  }
+  /**
+   * Get a specific plugin's manifest by ID.
+   *
+   * @param pluginId - The unique plugin identifier.
+   * @returns The manifest if found, otherwise `undefined`.
+   */
+  getManifest(pluginId) {
+    return this.manifests.get(pluginId);
+  }
+  // -----------------------------------------------------------------------
+  // Enabled / disabled state
+  // -----------------------------------------------------------------------
+  /**
+   * Check whether a plugin is currently enabled.
+   *
+   * @param pluginId - The unique plugin identifier.
+   * @returns `true` if the plugin is enabled.
+   */
+  isEnabled(pluginId) {
+    return this.enabledPlugins.has(pluginId);
+  }
+  /**
+   * Enable a plugin and persist the state to `config.json`.
+   *
+   * @param pluginId - The unique plugin identifier.
+   */
+  enablePlugin(pluginId) {
+    this.enabledPlugins.add(pluginId);
+    this.logger.info({ pluginId }, `Plugin "${pluginId}" enabled`);
+    this.persistPluginState(pluginId, true);
+  }
+  /**
+   * Disable a plugin and persist the state to `config.json`.
+   *
+   * @param pluginId - The unique plugin identifier.
+   */
+  disablePlugin(pluginId) {
+    this.enabledPlugins.delete(pluginId);
+    this.logger.info({ pluginId }, `Plugin "${pluginId}" disabled`);
+    this.persistPluginState(pluginId, false);
+  }
+  /**
+   * Get the list of currently-enabled plugin IDs.
+   *
+   * @returns Array of enabled plugin ID strings.
+   */
+  getEnabledPluginIds() {
+    return Array.from(this.enabledPlugins);
+  }
+  /**
+   * Get the list of all discovered plugin IDs.
+   *
+   * @returns Array of all known plugin ID strings.
+   */
+  getAllPluginIds() {
+    return Array.from(this.manifests.keys());
+  }
+  // -----------------------------------------------------------------------
+  // Private helpers
+  // -----------------------------------------------------------------------
+  /**
+   * Load the enabled state for every discovered plugin from the application
+   * config.  Plugins whose config entry has `enabled: true` are added to the
+   * enabled set.
+   */
+  loadEnabledState() {
+    let appConfig;
+    try {
+      if (existsSync3(CONFIG_PATH)) {
+        const raw = JSON.parse(readFileSync3(CONFIG_PATH, "utf-8"));
+        appConfig = AppConfigSchema.parse(raw);
+      } else {
+        appConfig = AppConfigSchema.parse({});
+      }
+    } catch {
+      this.logger.warn("Could not load config.json \u2014 defaulting all plugins to disabled");
+      return;
+    }
+    const plugins = appConfig.plugins ?? {};
+    for (const id of this.manifests.keys()) {
+      if (plugins[id]?.enabled === true) {
+        this.enabledPlugins.add(id);
+        this.logger.debug({ pluginId: id }, `Plugin "${id}" is enabled via config`);
+      }
+    }
+  }
+  /**
+   * Persist the enabled/disabled state for a single plugin to `config.json`.
+   *
+   * Reads the current file, updates the relevant entry, and writes it back.
+   * If the file does not exist a minimal config is created.
+   */
+  persistPluginState(pluginId, enabled) {
+    try {
+      let config = {};
+      if (existsSync3(CONFIG_PATH)) {
+        config = JSON.parse(readFileSync3(CONFIG_PATH, "utf-8"));
+      }
+      if (!config.plugins || typeof config.plugins !== "object") {
+        config.plugins = {};
+      }
+      const plugins = config.plugins;
+      if (!plugins[pluginId]) {
+        plugins[pluginId] = { enabled, credentials: {} };
+      } else {
+        plugins[pluginId].enabled = enabled;
+      }
+      writeFileSync2(CONFIG_PATH, JSON.stringify(config, null, 2) + "\n", "utf-8");
+      resetConfig();
+      this.logger.debug(
+        { pluginId, enabled },
+        "Persisted plugin state to config.json"
+      );
+    } catch (err) {
+      this.logger.error(
+        { pluginId, error: err.message },
+        "Failed to persist plugin state to config.json"
+      );
+    }
+  }
+};
+function createPluginRegistry(pluginsDir) {
+  return new PluginRegistry(pluginsDir ?? path2.join(process.cwd(), "plugins"));
+}
+
+// src/plugins/manager.ts
+import path3 from "path";
+import { existsSync as existsSync4 } from "fs";
+import { tsImport } from "tsx/esm/api";
+var PluginManager = class {
+  constructor(registry, sandbox, credentials, stateRepo) {
+    this.registry = registry;
+    this.sandbox = sandbox;
+    this.credentials = credentials;
+    this.stateRepo = stateRepo;
+    this.logger = createChildLogger("plugins:manager");
+  }
+  registry;
+  sandbox;
+  credentials;
+  stateRepo;
+  /** Active (loaded and initialised) plugin instances keyed by ID. */
+  plugins = /* @__PURE__ */ new Map();
+  /** Current lifecycle status for every known plugin. */
+  pluginStatuses = /* @__PURE__ */ new Map();
+  /** Namespaced logger for manager operations. */
+  logger;
+  // -----------------------------------------------------------------------
+  // Initialisation
+  // -----------------------------------------------------------------------
+  /**
+   * Initialise the plugin system: discover plugins on disk, then load and
+   * initialise every enabled plugin.
+   *
+   * Safe to call exactly once at application startup. Errors from individual
+   * plugins are caught and logged — a single broken plugin never prevents the
+   * rest from loading.
+   */
+  async initialize() {
+    this.logger.info("Initializing plugin system\u2026");
+    const manifests = await this.registry.discoverPlugins();
+    const discovered = manifests.length;
+    let loaded = 0;
+    let failed = 0;
+    const enabledIds = this.registry.getEnabledPluginIds();
+    for (const pluginId of enabledIds) {
+      try {
+        await this.loadPlugin(pluginId);
+        loaded++;
+      } catch (err) {
+        failed++;
+        const error = err instanceof Error ? err : new Error(String(err));
+        this.logger.error(
+          { pluginId, error: error.message },
+          `Failed to load plugin "${pluginId}"`
+        );
+        this.pluginStatuses.set(pluginId, "error");
+      }
+    }
+    this.logger.info(
+      { discovered, loaded, failed },
+      `Plugin system ready \u2014 ${discovered} discovered, ${loaded} loaded, ${failed} failed`
+    );
+  }
+  // -----------------------------------------------------------------------
+  // Load / Unload
+  // -----------------------------------------------------------------------
+  /**
+   * Load and initialise a specific plugin by ID.
+   *
+   * Steps:
+   * 1. Resolve the plugin manifest from the registry.
+   * 2. Validate credentials via the {@link CredentialManager}.
+   * 3. Dynamically import the plugin module (preferring compiled `.js`).
+   * 4. Invoke the factory to obtain a {@link CoAssistantPlugin} instance.
+   * 5. Build a {@link PluginContext} and call `plugin.initialize()` inside
+   *    the sandbox.
+   * 6. Store the active plugin and set its status to `"active"`.
+   *
+   * @param pluginId - Unique identifier of the plugin to load.
+   * @throws If the manifest is not found, credentials are invalid, or the
+   *         module cannot be imported.
+   */
+  async loadPlugin(pluginId) {
+    this.logger.info({ pluginId }, `Loading plugin "${pluginId}"\u2026`);
+    const manifest = this.registry.getManifest(pluginId);
+    if (!manifest) {
+      throw new Error(`No manifest found for plugin "${pluginId}"`);
+    }
+    this.pluginStatuses.set(pluginId, "loaded");
+    let creds = {};
+    try {
+      creds = this.credentials.getValidatedCredentials(
+        pluginId,
+        manifest.requiredCredentials
+      );
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      this.logger.warn(
+        { pluginId, error: error.message },
+        `Credential validation failed for "${pluginId}" \u2014 loading with empty credentials`
+      );
+    }
+    const pluginPath = this.resolvePluginPath(pluginId);
+    this.logger.debug({ pluginId, pluginPath }, "Importing plugin module");
+    let mod;
+    try {
+      if (pluginPath.endsWith(".ts")) {
+        mod = await tsImport(pluginPath, import.meta.url);
+      } else {
+        mod = await import(pluginPath);
+      }
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      this.pluginStatuses.set(pluginId, "error");
+      throw new Error(
+        `Failed to import plugin module "${pluginId}" from ${pluginPath}: ${error.message}`
+      );
+    }
+    const factory = typeof mod.default === "function" ? mod.default : typeof mod.createPlugin === "function" ? mod.createPlugin : void 0;
+    if (!factory) {
+      this.pluginStatuses.set(pluginId, "error");
+      throw new Error(
+        `Plugin "${pluginId}" does not export a default factory or createPlugin function`
+      );
+    }
+    const plugin = factory();
+    const context = this.buildPluginContext(pluginId, creds);
+    const initResult = await this.sandbox.safeExecute(
+      pluginId,
+      "initialize",
+      () => plugin.initialize(context)
+    );
+    if (initResult === void 0 && manifest.requiredCredentials.length > 0) {
+      this.logger.warn(
+        { pluginId },
+        `Plugin "${pluginId}" initialize() did not succeed \u2014 marking as error`
+      );
+    }
+    this.plugins.set(pluginId, plugin);
+    this.pluginStatuses.set(pluginId, "active");
+    this.logger.info(
+      { pluginId, version: manifest.version },
+      `Plugin "${manifest.name}" v${manifest.version} loaded successfully`
+    );
+  }
+  /**
+   * Unload a plugin: invoke its `destroy()` hook inside the sandbox,
+   * remove it from the active plugin map, and mark it as unloaded.
+   *
+   * @param pluginId - Unique identifier of the plugin to unload.
+   */
+  async unloadPlugin(pluginId) {
+    const plugin = this.plugins.get(pluginId);
+    if (!plugin) {
+      this.logger.warn({ pluginId }, `Plugin "${pluginId}" is not loaded \u2014 nothing to unload`);
+      return;
+    }
+    this.logger.info({ pluginId }, `Unloading plugin "${pluginId}"\u2026`);
+    await this.sandbox.safeExecute(pluginId, "destroy", () => plugin.destroy());
+    this.plugins.delete(pluginId);
+    this.pluginStatuses.set(pluginId, "unloaded");
+    this.logger.info({ pluginId }, `Plugin "${pluginId}" unloaded`);
+  }
+  // -----------------------------------------------------------------------
+  // Enable / Disable
+  // -----------------------------------------------------------------------
+  /**
+   * Enable a plugin: persist the enabled state in the registry and load the
+   * plugin if it is not already active.
+   *
+   * @param pluginId - Unique identifier of the plugin to enable.
+   */
+  async enablePlugin(pluginId) {
+    this.logger.info({ pluginId }, `Enabling plugin "${pluginId}"`);
+    this.registry.enablePlugin(pluginId);
+    if (!this.plugins.has(pluginId)) {
+      await this.loadPlugin(pluginId);
+    }
+  }
+  /**
+   * Disable a plugin: persist the disabled state in the registry and unload
+   * the plugin if it is currently active.
+   *
+   * @param pluginId - Unique identifier of the plugin to disable.
+   */
+  async disablePlugin(pluginId) {
+    this.logger.info({ pluginId }, `Disabling plugin "${pluginId}"`);
+    this.registry.disablePlugin(pluginId);
+    if (this.plugins.has(pluginId)) {
+      await this.unloadPlugin(pluginId);
+    }
+    this.pluginStatuses.set(pluginId, "disabled");
+  }
+  // -----------------------------------------------------------------------
+  // Accessors
+  // -----------------------------------------------------------------------
+  /**
+   * Get all active (loaded and running) plugin instances.
+   *
+   * @returns A new Map containing only the currently active plugins.
+   */
+  getActivePlugins() {
+    return new Map(this.plugins);
+  }
+  /**
+   * Collect all tool definitions from every active plugin.
+   *
+   * Tool names are prefixed with the owning plugin's ID
+   * (`<pluginId>__<toolName>`) to guarantee uniqueness. Handlers are wrapped
+   * by the sandbox so errors are isolated.
+   *
+   * @returns Flat array of all tools across all active plugins.
+   */
+  getAllTools() {
+    const tools = [];
+    for (const [pluginId, plugin] of this.plugins) {
+      try {
+        const pluginTools = plugin.getTools();
+        for (const tool of pluginTools) {
+          tools.push({
+            name: `${pluginId}__${tool.name}`,
+            description: tool.description,
+            parameters: tool.parameters,
+            handler: this.sandbox.wrapToolHandler(pluginId, tool.name, tool.handler)
+          });
+        }
+      } catch (err) {
+        const error = err instanceof Error ? err : new Error(String(err));
+        this.logger.error(
+          { pluginId, error: error.message },
+          `Failed to get tools from plugin "${pluginId}"`
+        );
+      }
+    }
+    return tools;
+  }
+  /**
+   * Build a read-only info snapshot for every discovered plugin.
+   *
+   * Combines manifest metadata, current lifecycle status, enabled state,
+   * sandbox failure counts, and registered tool names.
+   *
+   * @returns Array of {@link PluginInfo} objects (for display / admin API).
+   */
+  getPluginInfoList() {
+    const manifests = this.registry.getManifests();
+    return manifests.map((manifest) => {
+      const pluginId = manifest.id;
+      const status = this.pluginStatuses.get(pluginId) ?? "unloaded";
+      const enabled = this.registry.isEnabled(pluginId);
+      const failureCount = this.sandbox.getFailureCount(pluginId);
+      let toolNames = [];
+      const plugin = this.plugins.get(pluginId);
+      if (plugin) {
+        try {
+          toolNames = plugin.getTools().map((t) => `${pluginId}__${t.name}`);
+        } catch {
+        }
+      }
+      const info = {
+        id: pluginId,
+        name: manifest.name,
+        version: manifest.version,
+        description: manifest.description,
+        status,
+        enabled,
+        failureCount,
+        tools: toolNames
+      };
+      if (status === "error") {
+        info.errorMessage = this.sandbox.isDisabled(pluginId) ? "Auto-disabled due to repeated failures" : "Plugin encountered an error during lifecycle";
+      }
+      return info;
+    });
+  }
+  /**
+   * Get info about a specific discovered plugin.
+   *
+   * @param pluginId - The unique plugin identifier.
+   * @returns The plugin info snapshot, or `undefined` if the plugin was not
+   *          discovered.
+   */
+  getPluginInfo(pluginId) {
+    return this.getPluginInfoList().find((info) => info.id === pluginId);
+  }
+  // -----------------------------------------------------------------------
+  // Shutdown
+  // -----------------------------------------------------------------------
+  /**
+   * Gracefully shut down all active plugins.
+   *
+   * Calls `destroy()` on each plugin inside the sandbox so that a failing
+   * plugin does not prevent the rest from cleaning up.
+   */
+  async shutdown() {
+    this.logger.info("Shutting down plugin system\u2026");
+    const pluginIds = Array.from(this.plugins.keys());
+    for (const pluginId of pluginIds) {
+      await this.unloadPlugin(pluginId);
+    }
+    this.logger.info(
+      { count: pluginIds.length },
+      `Plugin system shut down \u2014 ${pluginIds.length} plugin(s) unloaded`
+    );
+  }
+  // -----------------------------------------------------------------------
+  // Private helpers
+  // -----------------------------------------------------------------------
+  /**
+   * Resolve the file-system path for a plugin module.
+   *
+   * Prefers the compiled `.js` file; falls back to `.ts` for development.
+   */
+  resolvePluginPath(pluginId) {
+    const baseDir = path3.join(process.cwd(), "plugins", pluginId);
+    const jsPath = path3.join(baseDir, "index.js");
+    if (existsSync4(jsPath)) {
+      return jsPath;
+    }
+    const tsPath = path3.join(baseDir, "index.ts");
+    if (existsSync4(tsPath)) {
+      return tsPath;
+    }
+    return jsPath;
+  }
+  /**
+   * Build a {@link PluginContext} for a specific plugin.
+   *
+   * The context provides credentials, a namespaced state store backed by the
+   * {@link PluginStateRepository}, and a child logger.
+   */
+  buildPluginContext(pluginId, credentials) {
+    const stateStore = {
+      get: (key) => this.stateRepo.get(pluginId, key),
+      set: (key, value) => this.stateRepo.set(pluginId, key, value),
+      delete: (key) => this.stateRepo.delete(pluginId, key),
+      getAll: () => this.stateRepo.getAll(pluginId)
+    };
+    return {
+      pluginId,
+      credentials,
+      state: stateStore,
+      logger: createChildLogger(`plugin:${pluginId}`, { pluginId })
+    };
+  }
+};
+function createPluginManager(registry, sandbox, credentials, stateRepo) {
+  return new PluginManager(registry, sandbox, credentials, stateRepo);
+}
+
+// src/plugins/sandbox.ts
+var DEFAULT_MAX_FAILURES = 5;
+var PluginSandbox = class {
+  /** Consecutive failure counts keyed by plugin ID. */
+  failureCounts = /* @__PURE__ */ new Map();
+  /** Set of plugin IDs that have been auto-disabled due to repeated failures. */
+  disabledPlugins = /* @__PURE__ */ new Set();
+  /** Maximum consecutive failures before a plugin is disabled. */
+  maxFailures;
+  /** Namespaced logger for sandbox events. */
+  logger;
+  /**
+   * Create a new sandbox instance.
+   *
+   * @param maxFailures - Override for the failure threshold. When omitted the
+   *   value is read from the application config (`app.pluginHealth.maxFailures`)
+   *   with a hard-coded fallback of {@link DEFAULT_MAX_FAILURES}.
+   */
+  constructor(maxFailures) {
+    this.logger = createChildLogger("plugins:sandbox");
+    if (maxFailures !== void 0) {
+      this.maxFailures = maxFailures;
+    } else {
+      try {
+        const { getConfig: getConfig2 } = (init_config(), __toCommonJS(config_exports));
+        this.maxFailures = getConfig2().app.pluginHealth.maxFailures ?? DEFAULT_MAX_FAILURES;
+      } catch {
+        this.maxFailures = DEFAULT_MAX_FAILURES;
+      }
+    }
+  }
+  // -----------------------------------------------------------------------
+  // Core execution wrapper
+  // -----------------------------------------------------------------------
+  /**
+   * Safely execute a plugin method within a try/catch boundary.
+   *
+   * If the plugin is disabled the call is short-circuited and `undefined` is
+   * returned.  On success the failure counter is reset; on failure it is
+   * incremented and the error is logged with full context.
+   *
+   * **Critical:** errors are _never_ allowed to propagate out of this method.
+   *
+   * @param pluginId   - Unique identifier of the plugin.
+   * @param methodName - Name of the method being invoked (for logging).
+   * @param fn         - The async function to execute.
+   * @returns The result of `fn()` on success, or `undefined` on failure.
+   */
+  async safeExecute(pluginId, methodName, fn) {
+    try {
+      if (this.isDisabled(pluginId)) {
+        this.logger.warn(
+          { pluginId, methodName },
+          `Plugin "${pluginId}" is disabled \u2014 skipping ${methodName}`
+        );
+        return void 0;
+      }
+      const result = await fn();
+      this.recordSuccess(pluginId);
+      return result;
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      this.recordFailure(pluginId, error, methodName);
+      this.logger.error(
+        {
+          pluginId,
+          methodName,
+          error: error.message,
+          failureCount: this.getFailureCount(pluginId),
+          maxFailures: this.maxFailures
+        },
+        `Plugin "${pluginId}" method "${methodName}" threw: ${error.message}`
+      );
+      return void 0;
+    }
+  }
+  // -----------------------------------------------------------------------
+  // Tool handler wrapper
+  // -----------------------------------------------------------------------
+  /**
+   * Wrap a tool handler so that errors are caught and returned as a
+   * descriptive string rather than crashing the process.
+   *
+   * The AI model therefore receives actionable feedback about the failure
+   * instead of an unhandled exception.
+   *
+   * @param pluginId - Unique identifier of the owning plugin.
+   * @param toolName - Display name of the tool.
+   * @param handler  - The original tool handler function.
+   * @returns A wrapped handler with identical signature.
+   */
+  wrapToolHandler(pluginId, toolName, handler) {
+    return async (args) => {
+      const result = await this.safeExecute(
+        pluginId,
+        `tool:${toolName}`,
+        () => handler(args)
+      );
+      if (result === void 0) {
+        return `Error: Tool ${toolName} failed: ${this.isDisabled(pluginId) ? "plugin has been disabled due to repeated failures" : "unexpected error during execution"}`;
+      }
+      return result;
+    };
+  }
+  // -----------------------------------------------------------------------
+  // Failure / success tracking
+  // -----------------------------------------------------------------------
+  /**
+   * Record a failure for a plugin and auto-disable it if the threshold is
+   * reached.
+   *
+   * @param pluginId   - Unique identifier of the plugin.
+   * @param error      - The error that occurred.
+   * @param methodName - The method that failed (for logging).
+   * @returns `true` if the plugin was auto-disabled as a result of this failure.
+   */
+  recordFailure(pluginId, error, methodName) {
+    const current = (this.failureCounts.get(pluginId) ?? 0) + 1;
+    this.failureCounts.set(pluginId, current);
+    try {
+      const { PluginHealthRepository: PluginHealthRepository2 } = (init_plugin_health(), __toCommonJS(plugin_health_exports));
+      const repo = new PluginHealthRepository2();
+      repo.logHealth(pluginId, "error", error.message);
+    } catch {
+    }
+    if (current >= this.maxFailures && !this.disabledPlugins.has(pluginId)) {
+      this.disabledPlugins.add(pluginId);
+      this.logger.warn(
+        {
+          pluginId,
+          methodName,
+          failureCount: current,
+          maxFailures: this.maxFailures
+        },
+        `Plugin "${pluginId}" auto-disabled after ${current} consecutive failures (threshold: ${this.maxFailures})`
+      );
+      return true;
+    }
+    return false;
+  }
+  /**
+   * Record a successful execution for a plugin.
+   *
+   * Resets the consecutive failure counter to zero — a successful call proves
+   * the plugin is healthy.
+   *
+   * @param pluginId - Unique identifier of the plugin.
+   */
+  recordSuccess(pluginId) {
+    this.failureCounts.set(pluginId, 0);
+  }
+  // -----------------------------------------------------------------------
+  // Status queries
+  // -----------------------------------------------------------------------
+  /**
+   * Check whether a plugin has been auto-disabled due to repeated failures.
+   *
+   * @param pluginId - Unique identifier of the plugin.
+   * @returns `true` if the plugin is currently disabled.
+   */
+  isDisabled(pluginId) {
+    return this.disabledPlugins.has(pluginId);
+  }
+  /**
+   * Get the current consecutive failure count for a plugin.
+   *
+   * @param pluginId - Unique identifier of the plugin.
+   * @returns The number of consecutive failures (0 when not tracked).
+   */
+  getFailureCount(pluginId) {
+    return this.failureCounts.get(pluginId) ?? 0;
+  }
+  /**
+   * Reset the failure counter and re-enable a previously disabled plugin.
+   *
+   * @param pluginId - Unique identifier of the plugin.
+   */
+  resetPlugin(pluginId) {
+    this.failureCounts.delete(pluginId);
+    this.disabledPlugins.delete(pluginId);
+    this.logger.info({ pluginId }, `Plugin "${pluginId}" has been reset and re-enabled`);
+  }
+  /**
+   * Build a health summary for every plugin the sandbox has interacted with.
+   *
+   * @returns A map from plugin ID to its current failure count and disabled
+   *   status.
+   */
+  getHealthSummary() {
+    const summary = /* @__PURE__ */ new Map();
+    for (const [pluginId, failures] of this.failureCounts) {
+      summary.set(pluginId, {
+        failures,
+        disabled: this.disabledPlugins.has(pluginId)
+      });
+    }
+    for (const pluginId of this.disabledPlugins) {
+      if (!summary.has(pluginId)) {
+        summary.set(pluginId, {
+          failures: 0,
+          disabled: true
+        });
+      }
+    }
+    return summary;
+  }
+};
+var pluginSandbox = new PluginSandbox();
+
+// src/plugins/credentials.ts
+init_config();
+var CredentialManager = class {
+  logger;
+  constructor() {
+    this.logger = createChildLogger("plugins:credentials");
+  }
+  /**
+   * Get credentials for a plugin from config.json.
+   * Returns the credentials `Record` or an empty object if not configured.
+   */
+  getPluginCredentials(pluginId) {
+    const { app } = getConfig();
+    return app.plugins[pluginId]?.credentials ?? {};
+  }
+  /**
+   * Validate that all required credentials are present and non-empty.
+   *
+   * @returns `{ valid: true }` when every required key is present with a
+   *   non-empty value, or `{ valid: false, missing }` listing the keys that
+   *   are absent or empty.
+   */
+  validateCredentials(pluginId, requiredCredentials) {
+    const credentials = this.getPluginCredentials(pluginId);
+    const missing = requiredCredentials.filter(({ key }) => {
+      const value = credentials[key];
+      return value === void 0 || value === "";
+    }).map(({ key }) => key);
+    if (missing.length === 0) {
+      this.logger.debug({ pluginId }, "All required credentials present");
+      return { valid: true };
+    }
+    this.logger.warn(
+      { pluginId, missing },
+      "Missing required credentials for plugin"
+    );
+    return { valid: false, missing };
+  }
+  /**
+   * Get credentials for a plugin, throwing {@link PluginError} if any
+   * required ones are missing.
+   *
+   * This is the main method plugins use during initialisation.
+   *
+   * @throws {PluginError} with code `PLUGIN_CREDENTIALS_MISSING` when one or
+   *   more required keys are absent or empty.
+   */
+  getValidatedCredentials(pluginId, requiredCredentials) {
+    const result = this.validateCredentials(pluginId, requiredCredentials);
+    if (!result.valid) {
+      throw PluginError.credentialsMissing(pluginId, result.missing);
+    }
+    this.logger.info(
+      { pluginId, count: requiredCredentials.length },
+      "Credentials validated successfully"
+    );
+    return this.getPluginCredentials(pluginId);
+  }
+  /**
+   * Check whether a plugin has all required credentials configured.
+   *
+   * Non-throwing convenience wrapper around {@link validateCredentials}.
+   */
+  hasRequiredCredentials(pluginId, requiredCredentials) {
+    return this.validateCredentials(pluginId, requiredCredentials).valid;
+  }
+  /**
+   * Get a summary of credential status for all known plugins.
+   * Useful for the CLI status command.
+   *
+   * @param plugins - Array of plugin descriptors containing their id and
+   *   required credential definitions.
+   * @returns Per-plugin breakdown of which credentials are configured vs
+   *   missing.
+   */
+  getCredentialStatus(plugins) {
+    return plugins.map(({ id, requiredCredentials }) => {
+      const credentials = this.getPluginCredentials(id);
+      const configured = [];
+      const missing = [];
+      for (const { key } of requiredCredentials) {
+        const value = credentials[key];
+        if (value !== void 0 && value !== "") {
+          configured.push(key);
+        } else {
+          missing.push(key);
+        }
+      }
+      return { pluginId: id, configured, missing };
+    });
+  }
+};
+var credentialManager = new CredentialManager();
+
+// src/bot/bot.ts
+import { Telegraf } from "telegraf";
+import { message } from "telegraf/filters";
+
+// src/bot/middleware/logging.ts
+var logger4 = createChildLogger("bot:middleware:logging");
+function createLoggingMiddleware() {
+  return async (ctx, next) => {
+    const start = Date.now();
+    const updateId = ctx.update.update_id;
+    const updateType = ctx.updateType;
+    const userId = ctx.from?.id;
+    const rawText = (ctx.message && "text" in ctx.message ? ctx.message.text : void 0) ?? (ctx.callbackQuery && "data" in ctx.callbackQuery ? ctx.callbackQuery.data : void 0);
+    const preview = rawText ? rawText.slice(0, 50) : void 0;
+    logger4.debug(
+      { updateId, updateType, userId, preview },
+      "Incoming update"
+    );
+    await next();
+    const durationMs = Date.now() - start;
+    logger4.debug(
+      { updateId, updateType, userId, durationMs },
+      "Update processed"
+    );
+  };
+}
+
+// src/bot/middleware/auth.ts
+var logger5 = createChildLogger("bot:auth");
+function createAuthMiddleware(allowedUserId) {
+  return async (ctx, next) => {
+    const senderId = ctx.from?.id;
+    if (senderId === void 0) {
+      logger5.warn(
+        { updateId: ctx.update.update_id },
+        "Update has no sender \u2014 dropping"
+      );
+      return;
+    }
+    if (senderId !== allowedUserId) {
+      const username = ctx.from?.username;
+      logger5.warn(
+        { senderId, username, allowedUserId, updateId: ctx.update.update_id },
+        "Unauthorized access attempt \u2014 dropping update"
+      );
+      return;
+    }
+    await next();
+  };
+}
+
+// src/bot/bot.ts
+var TelegramBot = class {
+  bot;
+  isRunning = false;
+  logger;
+  /**
+   * @param token - The Telegram Bot API token obtained from BotFather.
+   */
+  constructor(token) {
+    this.bot = new Telegraf(token);
+    this.logger = createChildLogger("bot");
+  }
+  // -----------------------------------------------------------------------
+  // Initialisation
+  // -----------------------------------------------------------------------
+  /**
+   * Register the middleware stack and message / command handlers.
+   *
+   * **Must** be called before {@link launch}. Middleware is applied in the
+   * following order:
+   *
+   * 1. Logging middleware — logs every incoming update
+   * 2. Auth guard middleware — drops unauthorised updates
+   * 3. Error-handling middleware — catches downstream errors
+   * 4. Command handler (if `onCommand` provided)
+   * 5. Text-message handler
+   * 6. Catch-all for unhandled update types
+   */
+  initialize(options) {
+    const { allowedUserId, onMessage, onCommand } = options;
+    this.bot.use(createLoggingMiddleware());
+    this.bot.use(createAuthMiddleware(allowedUserId));
+    this.bot.use(async (ctx, next) => {
+      try {
+        await next();
+      } catch (err) {
+        const errorMessage = err instanceof Error ? err.message : String(err);
+        this.logger.error(
+          { err, updateId: ctx.update.update_id },
+          "Unhandled error in middleware chain"
+        );
+        try {
+          await ctx.reply(
+            "\u26A0\uFE0F An unexpected error occurred. Please try again later."
+          );
+        } catch (replyErr) {
+          this.logger.error(
+            { err: replyErr },
+            "Failed to send error reply to user"
+          );
+        }
+      }
+    });
+    if (onCommand) {
+      this.bot.on(message("text"), async (ctx, next) => {
+        const text = ctx.message.text;
+        if (!text.startsWith("/")) {
+          return next();
+        }
+        const parts = text.slice(1).split(/\s+/);
+        const command = parts[0] ?? "";
+        const cleanCommand = command.split("@")[0];
+        const args = parts.slice(1).join(" ");
+        onCommand(ctx, cleanCommand, args).catch((err) => {
+          this.logger.error({ err, command: cleanCommand }, "Unhandled error in command handler");
+        });
+      });
+    }
+    this.bot.on(message("text"), async (ctx) => {
+      onMessage(ctx, ctx.message.text).catch((err) => {
+        this.logger.error({ err }, "Unhandled error in message handler");
+      });
+    });
+    this.bot.on("message", (ctx) => {
+      this.logger.debug(
+        { updateType: ctx.updateType, messageType: "non-text" },
+        "Received non-text message \u2014 ignoring"
+      );
+    });
+    this.logger.info("Bot initialised \u2014 middleware and handlers registered");
+  }
+  // -----------------------------------------------------------------------
+  // Lifecycle
+  // -----------------------------------------------------------------------
+  /**
+   * Start the bot in long-polling mode.
+   *
+   * Telegraf's `launch()` never resolves — it runs the polling loop forever.
+   * We use the `onLaunch` callback to detect when the initial handshake
+   * (getMe + deleteWebhook) succeeds, then let polling continue in the
+   * background.
+   *
+   * @throws {Error} If the Telegram API is unreachable after all retry attempts.
+   */
+  async launch() {
+    if (this.isRunning) {
+      this.logger.warn("launch() called but bot is already running");
+      return;
+    }
+    const maxRetries = 3;
+    const retryDelayMs = 5e3;
+    const connectTimeoutMs = 3e4;
+    for (let attempt = 1; attempt <= maxRetries; attempt++) {
+      try {
+        await new Promise((resolve, reject) => {
+          const timer = setTimeout(
+            () => reject(Object.assign(
+              new Error("Telegram connection timed out"),
+              { code: "ETIMEDOUT" }
+            )),
+            connectTimeoutMs
+          );
+          this.bot.launch(() => {
+            clearTimeout(timer);
+            resolve();
+          }).catch((err) => {
+            clearTimeout(timer);
+            reject(err);
+          });
+        });
+        this.isRunning = true;
+        const botInfo = this.bot.botInfo;
+        if (botInfo) {
+          this.logger.info(
+            { username: botInfo.username },
+            `Bot launched as @${botInfo.username}`
+          );
+        } else {
+          this.logger.info("Bot launched (username not yet available)");
+        }
+        return;
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        const code = err.code;
+        const isNetworkError = code === "ETIMEDOUT" || code === "ECONNREFUSED" || code === "ENOTFOUND" || code === "EAI_AGAIN" || code === "ENETUNREACH";
+        if (isNetworkError && attempt < maxRetries) {
+          console.log(`  \u26A0 Telegram connection failed (${code}). Retrying in ${retryDelayMs / 1e3}s\u2026 (${attempt}/${maxRetries})`);
+          this.logger.warn(
+            { attempt, maxRetries, code },
+            `Telegram connection failed (${code}). Retrying in ${retryDelayMs / 1e3}s\u2026`
+          );
+          await new Promise((r) => setTimeout(r, retryDelayMs));
+          continue;
+        }
+        this.logger.error({ err, code }, `Failed to connect to Telegram API: ${msg}`);
+        throw new Error(
+          `Could not connect to Telegram (${code || "UNKNOWN"}): ${msg}
+  \u2192 Check your internet connection and bot token.
+  \u2192 Verify the token with: https://api.telegram.org/bot<TOKEN>/getMe`
+        );
+      }
+    }
+  }
+  /**
+   * Stop the bot gracefully.
+   *
+   * Safe to call multiple times — subsequent calls are no-ops.
+   */
+  async stop() {
+    if (!this.isRunning) {
+      this.logger.debug("stop() called but bot is not running");
+      return;
+    }
+    this.bot.stop("graceful shutdown");
+    this.isRunning = false;
+    this.logger.info("Bot stopped");
+  }
+  // -----------------------------------------------------------------------
+  // Accessors
+  // -----------------------------------------------------------------------
+  /**
+   * Return the underlying Telegraf instance for advanced or low-level usage.
+   */
+  getBot() {
+    return this.bot;
+  }
+  /**
+   * Check whether the bot is currently running (polling).
+   */
+  isActive() {
+    return this.isRunning;
+  }
+};
+function createBot(token) {
+  return new TelegramBot(token);
+}
+
+// src/bot/handlers/message.ts
+var logger6 = createChildLogger("bot:handlers");
+function splitMessage(text, maxLength = 4096) {
+  if (text.length <= maxLength) {
+    return [text];
+  }
+  const chunks = [];
+  let remaining = text;
+  while (remaining.length > 0) {
+    if (remaining.length <= maxLength) {
+      chunks.push(remaining);
+      break;
+    }
+    let splitIdx = remaining.lastIndexOf("\n\n", maxLength);
+    if (splitIdx <= 0) {
+      splitIdx = remaining.lastIndexOf("\n", maxLength);
+    }
+    if (splitIdx <= 0) {
+      splitIdx = maxLength;
+    }
+    chunks.push(remaining.slice(0, splitIdx));
+    remaining = remaining.slice(splitIdx).replace(/^\n+/, "");
+  }
+  return chunks.filter((c) => c.length > 0);
+}
+function createMessageHandler(deps) {
+  const { sessionManager: sessionManager2, conversationRepo } = deps;
+  return async (ctx, text) => {
+    const replyToId = ctx.message?.message_id;
+    const replyOpts = replyToId ? { reply_parameters: { message_id: replyToId } } : {};
+    await ctx.sendChatAction("typing");
+    if (sessionManager2.getAvailableCount() === 0) {
+      await ctx.reply("\u23F3 All AI sessions busy \u2014 your message is queued.", replyOpts);
+    }
+    conversationRepo.addMessage("user", text);
+    logger6.debug({ textLength: text.length }, "User message stored");
+    if (!sessionManager2.isActive()) {
+      logger6.error("No active AI session \u2014 cannot process message");
+      await ctx.reply("\u26A0\uFE0F AI session is not active. Please restart the bot.", replyOpts);
+      return;
+    }
+    const typingInterval = setInterval(() => {
+      ctx.sendChatAction("typing").catch(() => {
+      });
+    }, 4e3);
+    try {
+      const response = await sessionManager2.sendMessage(text);
+      if (!response) {
+        logger6.warn("AI returned an empty response");
+        await ctx.reply("The AI returned an empty response. Please try again.", replyOpts);
+        return;
+      }
+      const model = sessionManager2.getCurrentModel();
+      conversationRepo.addMessage("assistant", response, model);
+      logger6.debug(
+        { responseLength: response.length, model },
+        "Assistant response stored"
+      );
+      const chunks = splitMessage(response);
+      for (const chunk of chunks) {
+        await ctx.reply(chunk, replyOpts);
+      }
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error);
+      logger6.error({ err: error }, "Failed to process message through AI");
+      await ctx.reply("Sorry, I couldn't process that. Please try again.", replyOpts);
+    } finally {
+      clearInterval(typingInterval);
+    }
+  };
+}
+
+// src/core/heartbeat.ts
+import { readdirSync as readdirSync2, readFileSync as readFileSync4, writeFileSync as writeFileSync3, unlinkSync, existsSync as existsSync5, mkdirSync as mkdirSync3 } from "fs";
+import { join, basename } from "path";
+var HEARTBEATS_DIR = "./heartbeats";
+var HEARTBEAT_EXT = ".heartbeat.md";
+var STATE_EXT = ".state.json";
+var DEDUP_PLACEHOLDER = "{{DEDUP_STATE}}";
+var MAX_STATE_IDS = 200;
+var PROCESSED_MARKER_RE = /<!--\s*PROCESSED:\s*(.*?)\s*-->/gi;
+var HeartbeatManager = class {
+  logger;
+  timer = null;
+  isRunning = false;
+  /** Prevents overlapping cycles when a run takes longer than the interval. */
+  cycleInProgress = false;
+  constructor() {
+    this.logger = createChildLogger("heartbeat");
+    ensureHeartbeatsDir();
+  }
+  // -----------------------------------------------------------------------
+  // File operations
+  // -----------------------------------------------------------------------
+  /**
+   * Discover all heartbeat event files in the heartbeats directory.
+   *
+   * @returns Array of {@link HeartbeatEvent} objects, one per file.
+   */
+  listEvents() {
+    ensureHeartbeatsDir();
+    const files = readdirSync2(HEARTBEATS_DIR).filter((f) => f.endsWith(HEARTBEAT_EXT));
+    return files.map((file) => {
+      const filePath = join(HEARTBEATS_DIR, file);
+      const name = basename(file, HEARTBEAT_EXT);
+      const prompt = readFileSync4(filePath, "utf-8").trim();
+      return { name, prompt, filePath };
+    });
+  }
+  /**
+   * Add a new heartbeat event by creating a `.heartbeat.md` file.
+   *
+   * @param name   - Event name (used as the filename, kebab-cased).
+   * @param prompt - The prompt text to send to the AI on each heartbeat.
+   * @throws {Error} If an event with the same name already exists.
+   */
+  addEvent(name, prompt) {
+    ensureHeartbeatsDir();
+    const safeName = name.toLowerCase().replace(/\s+/g, "-").replace(/[^a-z0-9-]/g, "");
+    const filePath = join(HEARTBEATS_DIR, `${safeName}${HEARTBEAT_EXT}`);
+    if (existsSync5(filePath)) {
+      throw new Error(`Heartbeat event "${safeName}" already exists at ${filePath}`);
+    }
+    writeFileSync3(filePath, prompt.trim() + "\n", "utf-8");
+    this.logger.info({ name: safeName, filePath }, "Heartbeat event created");
+  }
+  /**
+   * Remove a heartbeat event by name.
+   *
+   * @param name - The event name to remove.
+   * @throws {Error} If the event does not exist.
+   */
+  removeEvent(name) {
+    const safeName = name.toLowerCase().replace(/\s+/g, "-").replace(/[^a-z0-9-]/g, "");
+    const filePath = join(HEARTBEATS_DIR, `${safeName}${HEARTBEAT_EXT}`);
+    if (!existsSync5(filePath)) {
+      throw new Error(`Heartbeat event "${safeName}" not found`);
+    }
+    unlinkSync(filePath);
+    const statePath = join(HEARTBEATS_DIR, `${safeName}${STATE_EXT}`);
+    if (existsSync5(statePath)) {
+      unlinkSync(statePath);
+    }
+    this.logger.info({ name: safeName }, "Heartbeat event removed");
+  }
+  // -----------------------------------------------------------------------
+  // Deduplication state
+  // -----------------------------------------------------------------------
+  /**
+   * Load the persisted deduplication state for an event.
+   *
+   * @param eventName - The event name (kebab-cased, no extension).
+   * @returns The stored state, or a fresh empty state if none exists.
+   */
+  loadState(eventName) {
+    const statePath = join(HEARTBEATS_DIR, `${eventName}${STATE_EXT}`);
+    if (!existsSync5(statePath)) {
+      return { processedIds: [], lastRun: null };
+    }
+    try {
+      const raw = readFileSync4(statePath, "utf-8");
+      const parsed = JSON.parse(raw);
+      return {
+        processedIds: Array.isArray(parsed.processedIds) ? parsed.processedIds : [],
+        lastRun: parsed.lastRun ?? null
+      };
+    } catch (err) {
+      this.logger.warn({ err, eventName }, "Failed to parse state file \u2014 resetting");
+      return { processedIds: [], lastRun: null };
+    }
+  }
+  /**
+   * Persist deduplication state for an event. Caps stored IDs at
+   * {@link MAX_STATE_IDS} to prevent the file from growing unboundedly.
+   *
+   * @param eventName - The event name (kebab-cased, no extension).
+   * @param state     - The state to persist.
+   */
+  saveState(eventName, state) {
+    const statePath = join(HEARTBEATS_DIR, `${eventName}${STATE_EXT}`);
+    const trimmed = {
+      processedIds: state.processedIds.slice(-MAX_STATE_IDS),
+      lastRun: state.lastRun
+    };
+    writeFileSync3(statePath, JSON.stringify(trimmed, null, 2) + "\n", "utf-8");
+    this.logger.debug({ eventName, idCount: trimmed.processedIds.length }, "State saved");
+  }
+  /**
+   * Inject deduplication context into a prompt. If the prompt contains the
+   * `{{DEDUP_STATE}}` placeholder, it is replaced with a block listing the
+   * previously-processed IDs. If no placeholder is present, the prompt is
+   * returned unchanged.
+   *
+   * @param prompt - The raw prompt text from the `.heartbeat.md` file.
+   * @param state  - The loaded deduplication state.
+   * @returns The prompt with dedup context injected.
+   */
+  injectDedupContext(prompt, state) {
+    if (!prompt.includes(DEDUP_PLACEHOLDER)) {
+      return prompt;
+    }
+    if (state.processedIds.length === 0) {
+      return prompt.replace(DEDUP_PLACEHOLDER, "No previously processed items \u2014 this is the first run.");
+    }
+    const idList = state.processedIds.map((id) => `- ${id}`).join("\n");
+    const context = [
+      `Previously processed IDs (${state.processedIds.length} total) \u2014 SKIP these:`,
+      idList
+    ].join("\n");
+    return prompt.replace(DEDUP_PLACEHOLDER, context);
+  }
+  /**
+   * Extract newly-processed item IDs from the AI's response. Looks for
+   * `<!-- PROCESSED: id1, id2, id3 -->` markers anywhere in the text.
+   *
+   * @param response - The full AI response text.
+   * @returns Array of extracted IDs (may be empty if no marker found).
+   */
+  extractProcessedIds(response) {
+    const ids = [];
+    let match;
+    while ((match = PROCESSED_MARKER_RE.exec(response)) !== null) {
+      const raw = match[1] ?? "";
+      for (const id of raw.split(",")) {
+        const trimmed = id.trim();
+        if (trimmed) ids.push(trimmed);
+      }
+    }
+    PROCESSED_MARKER_RE.lastIndex = 0;
+    return ids;
+  }
+  // -----------------------------------------------------------------------
+  // Scheduling
+  // -----------------------------------------------------------------------
+  /**
+   * Start the heartbeat scheduler.
+   *
+   * Runs all heartbeat events immediately on first tick, then repeats at the
+   * configured interval.
+   *
+   * @param intervalMinutes - Minutes between each heartbeat cycle.
+   * @param sendFn          - Function that sends a prompt to the AI and returns the response.
+   * @param notifyFn        - Function that delivers the AI response to the user.
+   */
+  start(intervalMinutes, sendFn, notifyFn) {
+    if (this.isRunning) {
+      this.logger.warn("Heartbeat scheduler already running");
+      return;
+    }
+    if (intervalMinutes <= 0) {
+      this.logger.info("Heartbeat disabled (interval is 0)");
+      return;
+    }
+    const events = this.listEvents();
+    if (events.length === 0) {
+      this.logger.info("No heartbeat events found \u2014 scheduler idle");
+    }
+    const intervalMs = intervalMinutes * 60 * 1e3;
+    this.isRunning = true;
+    this.logger.info(
+      { intervalMinutes, eventCount: events.length },
+      `Heartbeat scheduler started (every ${intervalMinutes} min, ${events.length} events)`
+    );
+    const runCycle = async () => {
+      if (this.cycleInProgress) {
+        this.logger.debug("Skipping heartbeat cycle \u2014 previous cycle still in progress");
+        return;
+      }
+      this.cycleInProgress = true;
+      try {
+        const currentEvents = this.listEvents();
+        if (currentEvents.length === 0) return;
+        this.logger.debug({ count: currentEvents.length }, "Running heartbeat cycle");
+        for (const event of currentEvents) {
+          try {
+            this.logger.debug({ event: event.name }, `Executing heartbeat: ${event.name}`);
+            const useDedup = event.prompt.includes(DEDUP_PLACEHOLDER);
+            const state = useDedup ? this.loadState(event.name) : null;
+            const finalPrompt = state ? this.injectDedupContext(event.prompt, state) : event.prompt;
+            const response = await sendFn(finalPrompt);
+            if (response) {
+              if (useDedup && state) {
+                const newIds = this.extractProcessedIds(response);
+                if (newIds.length > 0) {
+                  const existing = new Set(state.processedIds);
+                  const uniqueNew = newIds.filter((id) => !existing.has(id));
+                  if (uniqueNew.length > 0) {
+                    state.processedIds.push(...uniqueNew);
+                    state.lastRun = (/* @__PURE__ */ new Date()).toISOString();
+                    this.saveState(event.name, state);
+                    this.logger.info(
+                      { event: event.name, newIds: uniqueNew.length, totalIds: state.processedIds.length },
+                      `Dedup: recorded ${uniqueNew.length} new IDs for "${event.name}"`
+                    );
+                  }
+                }
+              }
+              const cleanResponse = response.replace(PROCESSED_MARKER_RE, "").trim();
+              PROCESSED_MARKER_RE.lastIndex = 0;
+              if (cleanResponse) {
+                await notifyFn(event.name, cleanResponse);
+              }
+              this.logger.info({ event: event.name }, `Heartbeat "${event.name}" completed`);
+            } else {
+              this.logger.warn({ event: event.name }, `Heartbeat "${event.name}" returned no response`);
+            }
+          } catch (err) {
+            this.logger.error(
+              { err, event: event.name },
+              `Heartbeat "${event.name}" failed`
+            );
+          }
+        }
+      } finally {
+        this.cycleInProgress = false;
+      }
+    };
+    this.timer = setInterval(() => {
+      runCycle().catch((err) => {
+        this.logger.error({ err }, "Heartbeat cycle failed");
+      });
+    }, intervalMs);
+  }
+  /**
+   * Stop the heartbeat scheduler.
+   */
+  stop() {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    this.isRunning = false;
+    this.cycleInProgress = false;
+    this.logger.info("Heartbeat scheduler stopped");
+  }
+  /**
+   * Check whether the scheduler is currently running.
+   */
+  isActive() {
+    return this.isRunning;
+  }
+};
+function ensureHeartbeatsDir() {
+  if (!existsSync5(HEARTBEATS_DIR)) {
+    mkdirSync3(HEARTBEATS_DIR, { recursive: true });
+  }
+}
+
+// src/core/gc.ts
+var DEFAULT_INTERVAL_MINUTES = 30;
+var DEFAULT_CONVERSATION_RETENTION_DAYS = 30;
+var DEFAULT_HEALTH_RETENTION_DAYS = 7;
+var GarbageCollector = class {
+  logger;
+  timer = null;
+  db = null;
+  intervalMinutes;
+  conversationRetentionDays;
+  healthRetentionDays;
+  constructor(options) {
+    this.logger = createChildLogger("gc");
+    this.intervalMinutes = options?.intervalMinutes ?? DEFAULT_INTERVAL_MINUTES;
+    this.conversationRetentionDays = options?.conversationRetentionDays ?? DEFAULT_CONVERSATION_RETENTION_DAYS;
+    this.healthRetentionDays = options?.healthRetentionDays ?? DEFAULT_HEALTH_RETENTION_DAYS;
+  }
+  // -----------------------------------------------------------------------
+  // Lifecycle
+  // -----------------------------------------------------------------------
+  /**
+   * Start the periodic GC timer.
+   *
+   * @param db - The SQLite database handle to prune.
+   */
+  start(db) {
+    this.db = db;
+    if (this.intervalMinutes <= 0) {
+      this.logger.info("Garbage collector disabled (interval = 0)");
+      return;
+    }
+    this.runCycle();
+    const intervalMs = this.intervalMinutes * 6e4;
+    this.timer = setInterval(() => this.runCycle(), intervalMs);
+    if (this.timer.unref) this.timer.unref();
+    this.logger.info(
+      {
+        intervalMinutes: this.intervalMinutes,
+        conversationRetentionDays: this.conversationRetentionDays,
+        healthRetentionDays: this.healthRetentionDays
+      },
+      `GC started (every ${this.intervalMinutes} min)`
+    );
+  }
+  /**
+   * Stop the periodic GC timer.
+   */
+  stop() {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+      this.logger.info("GC stopped");
+    }
+  }
+  // -----------------------------------------------------------------------
+  // GC cycle
+  // -----------------------------------------------------------------------
+  /**
+   * Execute a single GC cycle: prune old records and log memory stats.
+   */
+  runCycle() {
+    const start = Date.now();
+    try {
+      const conversationsPruned = this.pruneConversations();
+      const healthPruned = this.prunePluginHealth();
+      const memStats = this.getMemoryStats();
+      const elapsed = Date.now() - start;
+      this.logger.info(
+        {
+          conversationsPruned,
+          healthPruned,
+          heapUsedMB: memStats.heapUsedMB,
+          rssMB: memStats.rssMB,
+          elapsed
+        },
+        `GC cycle complete \u2014 pruned ${conversationsPruned} conversations, ${healthPruned} health records (${elapsed}ms)`
+      );
+    } catch (err) {
+      this.logger.error({ err }, "GC cycle failed");
+    }
+  }
+  // -----------------------------------------------------------------------
+  // Pruning operations
+  // -----------------------------------------------------------------------
+  /**
+   * Delete conversation messages older than the retention window.
+   * @returns Number of rows deleted.
+   */
+  pruneConversations() {
+    if (!this.db) return 0;
+    try {
+      const result = this.db.prepare(
+        `DELETE FROM conversations
+         WHERE created_at < datetime('now', '-' || ? || ' days')`
+      ).run(this.conversationRetentionDays);
+      return result.changes;
+    } catch (err) {
+      this.logger.error({ err }, "Failed to prune conversations");
+      return 0;
+    }
+  }
+  /**
+   * Delete plugin health records older than the retention window.
+   * @returns Number of rows deleted.
+   */
+  prunePluginHealth() {
+    if (!this.db) return 0;
+    try {
+      const result = this.db.prepare(
+        `DELETE FROM plugin_health
+         WHERE checked_at < datetime('now', '-' || ? || ' days')`
+      ).run(this.healthRetentionDays);
+      return result.changes;
+    } catch (err) {
+      this.logger.error({ err }, "Failed to prune plugin health records");
+      return 0;
+    }
+  }
+  // -----------------------------------------------------------------------
+  // Memory monitoring
+  // -----------------------------------------------------------------------
+  /**
+   * Capture current process memory usage.
+   * @returns Object with heap and RSS in megabytes.
+   */
+  getMemoryStats() {
+    const mem = process.memoryUsage();
+    return {
+      heapUsedMB: Math.round(mem.heapUsed / 1024 / 1024 * 10) / 10,
+      heapTotalMB: Math.round(mem.heapTotal / 1024 / 1024 * 10) / 10,
+      rssMB: Math.round(mem.rss / 1024 / 1024 * 10) / 10,
+      externalMB: Math.round(mem.external / 1024 / 1024 * 10) / 10
+    };
+  }
+};
+
+// src/core/app.ts
+dns.setDefaultResultOrder("ipv4first");
+var App = class {
+  logger;
+  bot;
+  pluginManager;
+  heartbeatManager;
+  gc;
+  isShuttingDown = false;
+  verbose = false;
+  constructor() {
+    this.logger = createChildLogger("app");
+  }
+  // -----------------------------------------------------------------------
+  // Startup
+  // -----------------------------------------------------------------------
+  /**
+   * Boot the entire application.
+   *
+   * Initialisation order:
+   * 1. Configuration & logging
+   * 2. Database & repositories
+   * 3. Model registry
+   * 4. Plugin system (registry → manager)
+   * 5. Copilot AI client & session
+   * 6. Telegram bot (handlers → launch)
+   * 7. OS signal handlers for graceful shutdown
+   *
+   * @param options - Optional start-up flags.
+   */
+  async start(options) {
+    console.log("  \u25B8 Loading configuration\u2026");
+    const config = getConfig();
+    this.logger.info("Configuration loaded");
+    if (options?.verbose) {
+      setLogLevel("debug");
+      this.verbose = true;
+      this.logger.debug("Verbose logging enabled");
+    }
+    console.log("  \u25B8 Initializing database\u2026");
+    const db = getDatabase();
+    this.logger.info("Database ready");
+    const conversationRepo = new ConversationRepository(db);
+    const preferencesRepo = new PreferencesRepository(db);
+    const pluginStateRepo = new PluginStateRepository(db);
+    this.logger.info("Repositories created");
+    const gc = new GarbageCollector({
+      intervalMinutes: 30,
+      conversationRetentionDays: 30,
+      healthRetentionDays: 7
+    });
+    gc.start(db);
+    this.gc = gc;
+    const modelRegistry = createModelRegistry(preferencesRepo);
+    this.logger.info("Model registry initialised");
+    console.log("  \u25B8 Discovering plugins\u2026");
+    const pluginRegistry = createPluginRegistry();
+    await pluginRegistry.discoverPlugins();
+    const pluginManager = createPluginManager(
+      pluginRegistry,
+      pluginSandbox,
+      credentialManager,
+      pluginStateRepo
+    );
+    await pluginManager.initialize();
+    this.pluginManager = pluginManager;
+    this.logger.info("Plugin system ready");
+    console.log("  \u25B8 Starting Copilot SDK client\u2026");
+    await copilotClient.start();
+    const currentModel = modelRegistry.getCurrentModelId();
+    const activePlugins = pluginManager.getActivePlugins();
+    const pluginTools = pluginManager.getAllTools();
+    const poolSize = Math.max(1, parseInt(config.env.AI_SESSION_POOL_SIZE || "3", 10));
+    console.log(`  \u25B8 Creating AI session pool (model: ${currentModel}, sessions: ${poolSize})\u2026`);
+    await sessionManager.createSession(currentModel, pluginTools, poolSize);
+    console.log("  \u25B8 Connecting to Telegram\u2026");
+    const bot = createBot(config.env.TELEGRAM_BOT_TOKEN);
+    const rawMessageHandler = createMessageHandler({
+      sessionManager,
+      conversationRepo
+    });
+    const messageHandler = async (ctx, text) => {
+      const ts = () => (/* @__PURE__ */ new Date()).toLocaleTimeString();
+      const preview = text.length > 60 ? text.slice(0, 60) + "\u2026" : text;
+      if (this.verbose) {
+        console.log(`  \u21E3 [${ts()}] Message received: "${preview}"`);
+      }
+      const startTime = Date.now();
+      await rawMessageHandler(ctx, text);
+      if (this.verbose) {
+        const elapsed = ((Date.now() - startTime) / 1e3).toFixed(1);
+        console.log(`  \u21E1 [${ts()}] Message completed (${elapsed}s)`);
+      }
+    };
+    const heartbeatManager = new HeartbeatManager();
+    this.heartbeatManager = heartbeatManager;
+    const runHeartbeatOnDemand = async (ctx, eventName) => {
+      const replyToId = ctx.message?.message_id;
+      const replyOpts = replyToId ? { reply_parameters: { message_id: replyToId } } : {};
+      const allEvents = heartbeatManager.listEvents();
+      if (allEvents.length === 0) {
+        await ctx.reply("No heartbeat events configured.\nAdd one with: co-assistant heartbeat add", replyOpts);
+        return;
+      }
+      let eventsToRun = allEvents;
+      if (eventName) {
+        const match = allEvents.find((e) => e.name === eventName);
+        if (!match) {
+          const names = allEvents.map((e) => e.name).join(", ");
+          await ctx.reply(`\u274C Heartbeat "${eventName}" not found.
+Available: ${names}`, replyOpts);
+          return;
+        }
+        eventsToRun = [match];
+      }
+      await ctx.reply(`\u{1F680} Running ${eventsToRun.length} heartbeat event(s)\u2026`, replyOpts);
+      const typingInterval = setInterval(() => {
+        ctx.sendChatAction("typing").catch(() => {
+        });
+      }, 4e3);
+      try {
+        for (const event of eventsToRun) {
+          try {
+            const useDedup = event.prompt.includes("{{DEDUP_STATE}}");
+            const state = useDedup ? heartbeatManager.loadState(event.name) : null;
+            let finalPrompt = event.prompt;
+            if (state) {
+              finalPrompt = event.prompt.replace(
+                "{{DEDUP_STATE}}",
+                state.processedIds.length > 0 ? `Previously processed IDs (${state.processedIds.length} total) \u2014 SKIP these:
+${state.processedIds.map((id) => `- ${id}`).join("\n")}` : "No previously processed items \u2014 this is the first run."
+              );
+            }
+            const response = await sessionManager.sendMessage(finalPrompt);
+            if (!response) {
+              await ctx.reply(`\u26A0\uFE0F Heartbeat "${event.name}" returned no response.`, replyOpts);
+              continue;
+            }
+            const processedRe = /<!--\s*PROCESSED:\s*(.*?)\s*-->/gi;
+            if (useDedup && state) {
+              const existing = new Set(state.processedIds);
+              let m;
+              while ((m = processedRe.exec(response)) !== null) {
+                for (const id of (m[1] ?? "").split(",")) {
+                  const t = id.trim();
+                  if (t && !existing.has(t)) {
+                    state.processedIds.push(t);
+                    existing.add(t);
+                  }
+                }
+              }
+              processedRe.lastIndex = 0;
+              state.lastRun = (/* @__PURE__ */ new Date()).toISOString();
+              heartbeatManager.saveState(event.name, state);
+            }
+            const clean = response.replace(/<!--\s*PROCESSED:\s*.*?\s*-->/gi, "").trim();
+            if (clean) {
+              const header = `\u{1F493} *Heartbeat: ${event.name}*
+
+`;
+              const chunks = splitMessage(header + clean);
+              for (const chunk of chunks) {
+                await ctx.reply(chunk, { parse_mode: "Markdown", ...replyOpts });
+              }
+            }
+          } catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            this.logger.error({ err, event: event.name }, "On-demand heartbeat failed");
+            await ctx.reply(`\u274C Heartbeat "${event.name}" failed: ${msg}`, replyOpts);
+          }
+        }
+      } finally {
+        clearInterval(typingInterval);
+      }
+    };
+    const commandHandler = async (ctx, command, args) => {
+      const ts = () => (/* @__PURE__ */ new Date()).toLocaleTimeString();
+      const replyToId = ctx.message?.message_id;
+      const replyOpts = replyToId ? { reply_parameters: { message_id: replyToId } } : {};
+      if (this.verbose) {
+        console.log(`  \u21E3 [${ts()}] Command received: /${command}${args ? " " + args : ""}`);
+      }
+      const startTime = Date.now();
+      switch (command) {
+        case "heartbeat":
+        case "hb":
+          await runHeartbeatOnDemand(ctx, args.trim() || void 0);
+          break;
+        case "help":
+          await ctx.reply(
+            "\u{1F916} *Co-Assistant Commands*\n\n/heartbeat \\[name\\] \u2014 Run heartbeat event\\(s\\)\n/hb \\[name\\] \u2014 Shorthand for /heartbeat\n/help \u2014 Show this message\n\nOr just send a message to chat with the AI\\.",
+            { parse_mode: "MarkdownV2", ...replyOpts }
+          );
+          break;
+        default:
+          await messageHandler(ctx, `/${command} ${args}`.trim());
+      }
+      if (this.verbose) {
+        const elapsed = ((Date.now() - startTime) / 1e3).toFixed(1);
+        console.log(`  \u21E1 [${ts()}] Command completed: /${command} (${elapsed}s)`);
+      }
+    };
+    bot.initialize({
+      allowedUserId: Number(config.env.TELEGRAM_USER_ID),
+      onMessage: messageHandler,
+      onCommand: commandHandler
+    });
+    try {
+      await bot.launch();
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      this.logger.error({ err }, "Telegram bot failed to start");
+      console.error(`
+\u2717 Telegram bot failed to start:
+  ${msg}
+`);
+      await this.shutdown();
+      return;
+    }
+    this.bot = bot;
+    const pluginCount = activePlugins.size;
+    const botUsername = bot.getBot().botInfo?.username ?? "unknown";
+    const pluginNames = [...activePlugins.keys()].join(", ") || "none";
+    this.logger.info(
+      { model: currentModel, plugins: pluginCount, version: "1.0.0" },
+      `Co-Assistant is running! Model: ${currentModel}, Plugins: ${pluginCount}`
+    );
+    console.log("");
+    console.log("  \u2554\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2557");
+    console.log("  \u2551         \u{1F916} Co-Assistant is running!          \u2551");
+    console.log("  \u255A\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u255D");
+    console.log("");
+    console.log(`  Bot:     @${botUsername}`);
+    console.log(`  Model:   ${currentModel}`);
+    console.log(`  Sessions: ${poolSize} (parallel processing)`);
+    console.log(`  Plugins: ${pluginNames} (${pluginCount} active)`);
+    const heartbeatInterval = parseInt(config.env.HEARTBEAT_INTERVAL_MINUTES || "0", 10);
+    const heartbeatEvents = heartbeatManager.listEvents();
+    if (heartbeatInterval > 0 && heartbeatEvents.length > 0) {
+      heartbeatManager.start(
+        heartbeatInterval,
+        // Send heartbeat prompt to the AI session
+        async (prompt) => sessionManager.sendMessage(prompt),
+        // Forward the AI's response to the user via Telegram
+        async (eventName, response) => {
+          try {
+            const chatId = config.env.TELEGRAM_USER_ID;
+            const header = `\u{1F493} *Heartbeat: ${eventName}*
+
+`;
+            const fullMessage = header + response;
+            const chunks = splitMessage(fullMessage);
+            for (const chunk of chunks) {
+              await bot.getBot().telegram.sendMessage(chatId, chunk, { parse_mode: "Markdown" });
+            }
+          } catch (err) {
+            this.logger.error({ err, eventName }, "Failed to send heartbeat response via Telegram");
+          }
+        }
+      );
+      console.log(`  Heartbeat: every ${heartbeatInterval} min (${heartbeatEvents.length} events)`);
+    } else if (heartbeatInterval > 0) {
+      console.log(`  Heartbeat: every ${heartbeatInterval} min (no events \u2014 add with: co-assistant heartbeat add)`);
+    } else {
+      console.log("  Heartbeat: disabled (set HEARTBEAT_INTERVAL_MINUTES in .env)");
+    }
+    console.log("");
+    console.log("  Open Telegram and send a message to your bot to get started.");
+    console.log("  Press Ctrl+C to stop.\n");
+    const shutdownHandler = async (signal) => {
+      this.logger.info({ signal }, "Received shutdown signal");
+      await this.shutdown();
+    };
+    process.once("SIGINT", () => shutdownHandler("SIGINT"));
+    process.once("SIGTERM", () => shutdownHandler("SIGTERM"));
+  }
+  // -----------------------------------------------------------------------
+  // Shutdown
+  // -----------------------------------------------------------------------
+  /**
+   * Gracefully shut down all subsystems in reverse order.
+   *
+   * Each step is wrapped in its own try/catch so a failure in one subsystem
+   * never prevents the others from cleaning up.
+   */
+  async shutdown() {
+    if (this.isShuttingDown) {
+      this.logger.warn("Shutdown already in progress \u2014 skipping");
+      return;
+    }
+    this.isShuttingDown = true;
+    this.logger.info("Initiating graceful shutdown\u2026");
+    if (this.heartbeatManager) {
+      this.heartbeatManager.stop();
+      this.logger.info("Heartbeat scheduler stopped");
+    }
+    if (this.gc) {
+      this.gc.stop();
+    }
+    try {
+      if (this.bot) {
+        await this.bot.stop();
+        this.logger.info("Telegram bot stopped");
+      }
+    } catch (err) {
+      this.logger.error({ err }, "Error stopping Telegram bot");
+    }
+    try {
+      await sessionManager.closeSession();
+      this.logger.info("AI session closed");
+    } catch (err) {
+      this.logger.error({ err }, "Error closing AI session");
+    }
+    try {
+      await copilotClient.stop();
+      this.logger.info("Copilot client stopped");
+    } catch (err) {
+      this.logger.error({ err }, "Error stopping Copilot client");
+    }
+    try {
+      if (this.pluginManager) {
+        await this.pluginManager.shutdown();
+        this.logger.info("Plugins shut down");
+      }
+    } catch (err) {
+      this.logger.error({ err }, "Error shutting down plugins");
+    }
+    try {
+      closeDatabase();
+      this.logger.info("Database closed");
+    } catch (err) {
+      this.logger.error({ err }, "Error closing database");
+    }
+    this.logger.info("\u{1F44B} Goodbye!");
+    process.exit(0);
+  }
+};
+export {
+  App,
+  copilotClient,
+  sessionManager
+};
+//# sourceMappingURL=index.js.map