chainlesschain 0.45.75 → 0.45.76

package/src/lib/plugin-autodiscovery.js

@@ -0,0 +1,224 @@
+/**
+ * Plugin Auto-Discovery — zero-friction file-drop plugin loading.
+ *
+ * Scans ~/.chainlesschain/plugins/*.js for auto-loadable plugins.
+ * Hermes-style: drop a .js file, restart agent, it's available.
+ *
+ * Plugin exports:
+ *   { name, version?, description?, tools?, hooks?, commands? }
+ *
+ * - tools[]  → injected via extraTools in agent-core
+ * - hooks{}  → auto-registered in HookManager
+ * - commands{} → added to REPL slash commands
+ *
+ * DB-registered plugins (plugin-manager.js) override file-drop plugins
+ * with the same name.
+ *
+ * @module plugin-autodiscovery
+ */
+
+import { readdirSync, existsSync, mkdirSync } from "node:fs";
+import { join, extname, basename } from "node:path";
+import { pathToFileURL } from "node:url";
+import { getHomeDir } from "./paths.js";
+
+// ─── Constants ──────────────────────────────────────────────────────
+
+const PLUGINS_DIR_NAME = "plugins";
+
+// ─── Exported for test injection ────────────────────────────────────
+
+export const _deps = {
+  readdirSync,
+  existsSync,
+  mkdirSync,
+};
+
+// ─── Path ───────────────────────────────────────────────────────────
+
+/**
+ * Get the file-drop plugins directory path.
+ * @returns {string}
+ */
+export function getPluginDir() {
+  return join(getHomeDir(), PLUGINS_DIR_NAME);
+}
+
+// ─── Validation ─────────────────────────────────────────────────────
+
+/**
+ * Validate a plugin's exported shape.
+ * @param {object} mod - Module exports
+ * @param {string} filePath - Source file (for error messages)
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+export function validatePluginExports(mod, filePath) {
+  const errors = [];
+  const fname = basename(filePath);
+
+  if (!mod || typeof mod !== "object") {
+    return { valid: false, errors: [`${fname}: exports is not an object`] };
+  }
+
+  if (!mod.name || typeof mod.name !== "string") {
+    errors.push(`${fname}: missing or invalid 'name' (string required)`);
+  }
+
+  if (mod.tools && !Array.isArray(mod.tools)) {
+    errors.push(`${fname}: 'tools' must be an array`);
+  }
+
+  if (mod.hooks && typeof mod.hooks !== "object") {
+    errors.push(`${fname}: 'hooks' must be an object`);
+  }
+
+  if (mod.commands && typeof mod.commands !== "object") {
+    errors.push(`${fname}: 'commands' must be an object`);
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+// ─── Scan ───────────────────────────────────────────────────────────
+
+/**
+ * Scan the plugins directory and return .js file paths.
+ * @returns {string[]} Array of absolute paths to .js files
+ */
+export function scanPluginDir() {
+  const dir = getPluginDir();
+  if (!_deps.existsSync(dir)) {
+    return [];
+  }
+
+  try {
+    const entries = _deps.readdirSync(dir);
+    return entries.filter((f) => extname(f) === ".js").map((f) => join(dir, f));
+  } catch (_err) {
+    return [];
+  }
+}
+
+// ─── Load ───────────────────────────────────────────────────────────
+
+/**
+ * Load a single file-drop plugin.
+ * @param {string} filePath - Absolute path to the .js file
+ * @returns {Promise<{ plugin: object|null, errors: string[] }>}
+ */
+export async function loadFileDropPlugin(filePath) {
+  try {
+    const fileUrl = pathToFileURL(filePath).href;
+    const mod = await import(fileUrl);
+    // Handle both default export and named exports
+    const exports = mod.default || mod;
+
+    const { valid, errors } = validatePluginExports(exports, filePath);
+    if (!valid) {
+      return { plugin: null, errors };
+    }
+
+    return {
+      plugin: {
+        ...exports,
+        source: "file-drop",
+        filePath,
+      },
+      errors: [],
+    };
+  } catch (err) {
+    return {
+      plugin: null,
+      errors: [`${basename(filePath)}: load failed — ${err.message}`],
+    };
+  }
+}
+
+// ─── Discover All ───────────────────────────────────────────────────
+
+/**
+ * Discover and load all file-drop plugins.
+ * @param {object} [options]
+ * @param {string[]} [options.dbPluginNames] - Names of DB-registered plugins (these take priority)
+ * @param {function} [options.onWarn] - Warning callback (message) => void
+ * @returns {Promise<{ plugins: object[], errors: string[] }>}
+ */
+export async function getAutoDiscoveredPlugins(options = {}) {
+  const { dbPluginNames = [], onWarn } = options;
+  const dbNameSet = new Set(dbPluginNames);
+  const files = scanPluginDir();
+  const plugins = [];
+  const errors = [];
+
+  for (const filePath of files) {
+    const result = await loadFileDropPlugin(filePath);
+    if (result.errors.length > 0) {
+      errors.push(...result.errors);
+      if (onWarn) result.errors.forEach((e) => onWarn(e));
+      continue;
+    }
+
+    // DB-registered plugin with same name takes priority
+    if (dbNameSet.has(result.plugin.name)) {
+      if (onWarn) {
+        onWarn(
+          `Plugin "${result.plugin.name}" skipped (DB-registered version takes priority)`,
+        );
+      }
+      continue;
+    }
+
+    plugins.push(result.plugin);
+  }
+
+  return { plugins, errors };
+}
+
+// ─── Tool extraction ────────────────────────────────────────────────
+
+/**
+ * Extract tool definitions from loaded file-drop plugins.
+ * Returns tools in OpenAI function-calling format.
+ * @param {object[]} plugins - Loaded plugins from getAutoDiscoveredPlugins
+ * @returns {object[]} Tool definitions ready for extraTools
+ */
+export function extractPluginTools(plugins) {
+  const tools = [];
+  for (const plugin of plugins) {
+    if (!plugin.tools || !Array.isArray(plugin.tools)) continue;
+    for (const tool of plugin.tools) {
+      if (tool?.function?.name) {
+        tools.push({ ...tool, _pluginSource: plugin.name });
+      }
+    }
+  }
+  return tools;
+}
+
+/**
+ * Extract REPL commands from loaded file-drop plugins.
+ * @param {object[]} plugins - Loaded plugins
+ * @returns {Map<string, { handler: function, description: string, pluginName: string }>}
+ */
+export function extractPluginCommands(plugins) {
+  const commands = new Map();
+  for (const plugin of plugins) {
+    if (!plugin.commands || typeof plugin.commands !== "object") continue;
+    for (const [cmdName, cmdDef] of Object.entries(plugin.commands)) {
+      if (typeof cmdDef === "function") {
+        commands.set(cmdName, {
+          handler: cmdDef,
+          description: "",
+          pluginName: plugin.name,
+        });
+      } else if (cmdDef && typeof cmdDef.handler === "function") {
+        commands.set(cmdName, {
+          handler: cmdDef.handler,
+          description: cmdDef.description || "",
+          pluginName: plugin.name,
+        });
+      }
+    }
+  }
+  return commands;
+}

package/src/lib/session-search.js

@@ -0,0 +1,193 @@
+/**
+ * Session Search Index — cross-session FTS5 full-text search.
+ *
+ * Enables searching across all past agent sessions using SQLite FTS5.
+ * Indexes message content on SessionEnd and provides search with
+ * snippet highlighting.
+ *
+ * Inspired by Hermes Agent's cross-session FTS5 search.
+ *
+ * @module session-search
+ */
+
+import {
+  readEvents,
+  listJsonlSessions,
+} from "../harness/jsonl-session-store.js";
+
+// ─── Constants ──────────────────────────────────────────────────────────────
+
+const MAX_CONTENT_LENGTH = 10000; // per message, prevent bloat
+const DEFAULT_SEARCH_LIMIT = 10;
+
+// ─── SessionSearchIndex ─────────────────────────────────────────────────────
+
+export class SessionSearchIndex {
+  /**
+   * @param {object} db - better-sqlite3 database instance
+   */
+  constructor(db) {
+    this._db = db;
+    this._initialized = false;
+  }
+
+  /**
+   * Ensure FTS5 virtual table exists.
+   */
+  ensureTables() {
+    if (!this._db) return;
+    this._db.exec(`
+      CREATE VIRTUAL TABLE IF NOT EXISTS session_fts USING fts5(
+        session_id UNINDEXED,
+        role UNINDEXED,
+        content,
+        timestamp UNINDEXED,
+        tokenize='unicode61'
+      )
+    `);
+    this._initialized = true;
+  }
+
+  /**
+   * Extract text messages from a JSONL session.
+   * @param {string} sessionId
+   * @returns {Array<{role: string, content: string, timestamp: number}>}
+   */
+  extractMessages(sessionId) {
+    const events = readEvents(sessionId);
+    const messages = [];
+
+    for (const event of events) {
+      if (event.type === "user_message" || event.type === "assistant_message") {
+        const content = event.data?.content;
+        if (content && typeof content === "string" && content.trim()) {
+          messages.push({
+            role:
+              event.data.role ||
+              (event.type === "user_message" ? "user" : "assistant"),
+            content: content.substring(0, MAX_CONTENT_LENGTH),
+            timestamp: event.timestamp || 0,
+          });
+        }
+      }
+    }
+
+    return messages;
+  }
+
+  /**
+   * Index a single session's messages into the FTS table.
+   * Removes existing entries for this session first (idempotent).
+   *
+   * @param {string} sessionId
+   * @returns {{ indexed: number }} count of messages indexed
+   */
+  indexSession(sessionId) {
+    if (!this._db) return { indexed: 0 };
+    if (!this._initialized) this.ensureTables();
+
+    const messages = this.extractMessages(sessionId);
+    if (messages.length === 0) return { indexed: 0 };
+
+    // Remove existing entries for this session (idempotent re-index)
+    this._db.exec(
+      `DELETE FROM session_fts WHERE session_id = '${sessionId.replace(/'/g, "''")}'`,
+    );
+
+    const insert = this._db.prepare(
+      `INSERT INTO session_fts (session_id, role, content, timestamp) VALUES (?, ?, ?, ?)`,
+    );
+
+    const insertMany = this._db.transaction((msgs) => {
+      for (const msg of msgs) {
+        insert.run(sessionId, msg.role, msg.content, String(msg.timestamp));
+      }
+    });
+
+    insertMany(messages);
+    return { indexed: messages.length };
+  }
+
+  /**
+   * Search across all indexed sessions.
+   *
+   * @param {string} query - FTS5 search query
+   * @param {object} [options]
+   * @param {number} [options.limit=10] - Max results
+   * @returns {Array<{sessionId: string, role: string, snippet: string, timestamp: string, rank: number}>}
+   */
+  search(query, options = {}) {
+    if (!this._db) return [];
+    if (!this._initialized) this.ensureTables();
+    if (!query || !query.trim()) return [];
+
+    const limit = options.limit || DEFAULT_SEARCH_LIMIT;
+
+    // Use FTS5 match with highlight for snippet extraction
+    const stmt = this._db.prepare(`
+      SELECT
+        session_id as sessionId,
+        role,
+        highlight(session_fts, 2, '>>>', '<<<') as snippet,
+        timestamp,
+        rank
+      FROM session_fts
+      WHERE session_fts MATCH ?
+      ORDER BY rank
+      LIMIT ?
+    `);
+
+    try {
+      return stmt.all(query, limit);
+    } catch (_err) {
+      // FTS5 syntax error (e.g. special chars) — try as quoted phrase
+      try {
+        return stmt.all(`"${query.replace(/"/g, '""')}"`, limit);
+      } catch (_err2) {
+        return [];
+      }
+    }
+  }
+
+  /**
+   * Reindex all existing JSONL sessions into FTS.
+   * Useful for one-time backfill of historical sessions.
+   *
+   * @returns {{ sessions: number, messages: number }}
+   */
+  reindexAll() {
+    if (!this._db) return { sessions: 0, messages: 0 };
+    if (!this._initialized) this.ensureTables();
+
+    // Clear all existing FTS data
+    this._db.exec(`DELETE FROM session_fts`);
+
+    const sessions = listJsonlSessions({ limit: 10000 });
+    let totalMessages = 0;
+
+    for (const session of sessions) {
+      const result = this.indexSession(session.id);
+      totalMessages += result.indexed;
+    }
+
+    return { sessions: sessions.length, messages: totalMessages };
+  }
+
+  /**
+   * Get index statistics.
+   * @returns {{ totalRows: number }}
+   */
+  getStats() {
+    if (!this._db) return { totalRows: 0 };
+    if (!this._initialized) this.ensureTables();
+
+    try {
+      const row = this._db
+        .prepare(`SELECT COUNT(*) as cnt FROM session_fts`)
+        .get();
+      return { totalRows: row?.cnt || 0 };
+    } catch (_err) {
+      return { totalRows: 0 };
+    }
+  }
+}

package/src/lib/sub-agent-context.js

@@ -42,7 +42,8 @@ export class SubAgentContext {
    * @param {string} [options.parentId] - Parent context ID (null for root)
    * @param {string|null} [options.inheritedContext] - Condensed context from parent
    * @param {string[]} [options.allowedTools] - Tool whitelist (null = all tools)
-   * @param {number} [options.maxIterations] - Iteration limit
+   * @param {number} [options.maxIterations] - Iteration limit (fallback if no budget)
+   * @param {import('./iteration-budget.js').IterationBudget} [options.iterationBudget] - Shared iteration budget (takes priority over maxIterations)
    * @param {number} [options.tokenBudget] - Optional token budget
    * @param {object} [options.db] - Database instance
    * @param {object} [options.permanentMemory] - Permanent memory instance
@@ -61,6 +62,7 @@ export class SubAgentContext {
     this.role = options.role || "general";
     this.task = options.task || "";
     this.maxIterations = options.maxIterations || DEFAULT_MAX_ITERATIONS;
+    this.iterationBudget = options.iterationBudget || null; // shared budget from parent
     this.tokenBudget = options.tokenBudget || null;
     this.inheritedContext = options.inheritedContext || null;
     this.allowedTools = options.allowedTools || null; // null = all
@@ -207,13 +209,16 @@ export class SubAgentContext {
     // Build filtered tool list
     const tools = this._getFilteredTools();
 
-    // Merge LLM options
+    // Merge LLM options — pass shared iteration budget if available
     const options = {
       ...this._llmOptions,
       contextEngine: this.contextEngine,
       cwd: this.cwd,
       ...loopOptions,
     };
+    if (this.iterationBudget) {
+      options.iterationBudget = this.iterationBudget;
+    }
 
     try {
       // Use a separate messages array for the agent loop

package/src/lib/user-profile.js

@@ -0,0 +1,172 @@
+/**
+ * User Profile — persistent USER.md for AI-curated user preferences.
+ *
+ * Stores user preferences, coding style, communication style, and tech stack
+ * in a global USER.md file. AI-curated with character limit and automatic
+ * consolidation.
+ *
+ * Inspired by Hermes Agent's USER.md user profile system.
+ *
+ * @module user-profile
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { getHomeDir } from "./paths.js";
+
+// ─── Constants ──────────────────────────────────────────────────────────────
+
+const USER_PROFILE_FILENAME = "USER.md";
+const MAX_PROFILE_LENGTH = 2000; // characters
+
+// ─── Exported for test injection ────────────────────────────────────────────
+
+export const _deps = {
+  readFileSync,
+  writeFileSync,
+  existsSync,
+  mkdirSync,
+};
+
+// ─── Path ───────────────────────────────────────────────────────────────────
+
+/**
+ * Get the USER.md file path.
+ * @returns {string}
+ */
+export function getUserProfilePath() {
+  return join(getHomeDir(), USER_PROFILE_FILENAME);
+}
+
+// ─── Read ───────────────────────────────────────────────────────────────────
+
+/**
+ * Read the user profile content.
+ * @returns {string} Profile content, or empty string if not found
+ */
+export function readUserProfile() {
+  const profilePath = getUserProfilePath();
+  try {
+    if (_deps.existsSync(profilePath)) {
+      return _deps.readFileSync(profilePath, "utf-8");
+    }
+  } catch (_err) {
+    // Graceful degradation
+  }
+  return "";
+}
+
+// ─── Write ──────────────────────────────────────────────────────────────────
+
+/**
+ * Update the user profile with new content.
+ * Enforces MAX_PROFILE_LENGTH character limit.
+ *
+ * @param {string} content - New profile content
+ * @returns {{ written: boolean, truncated: boolean, length: number }}
+ */
+export function updateUserProfile(content) {
+  if (!content || typeof content !== "string") {
+    return { written: false, truncated: false, length: 0 };
+  }
+
+  const profilePath = getUserProfilePath();
+  const dir = dirname(profilePath);
+
+  try {
+    if (!_deps.existsSync(dir)) {
+      _deps.mkdirSync(dir, { recursive: true });
+    }
+
+    let truncated = false;
+    let finalContent = content.trim();
+    if (finalContent.length > MAX_PROFILE_LENGTH) {
+      finalContent = finalContent.substring(0, MAX_PROFILE_LENGTH);
+      truncated = true;
+    }
+
+    _deps.writeFileSync(profilePath, finalContent, "utf-8");
+    return { written: true, truncated, length: finalContent.length };
+  } catch (_err) {
+    return { written: false, truncated: false, length: 0 };
+  }
+}
+
+// ─── Append ─────────────────────────────────────────────────────────────────
+
+/**
+ * Append a line to the user profile.
+ * If the profile would exceed MAX_PROFILE_LENGTH, returns needsConsolidation: true.
+ *
+ * @param {string} line - Line to append
+ * @returns {{ appended: boolean, needsConsolidation: boolean, length: number }}
+ */
+export function appendToUserProfile(line) {
+  if (!line || typeof line !== "string") {
+    return { appended: false, needsConsolidation: false, length: 0 };
+  }
+
+  const current = readUserProfile();
+  const newContent = current ? `${current}\n${line.trim()}` : line.trim();
+
+  if (newContent.length > MAX_PROFILE_LENGTH) {
+    return {
+      appended: false,
+      needsConsolidation: true,
+      length: current.length,
+    };
+  }
+
+  const result = updateUserProfile(newContent);
+  return {
+    appended: result.written,
+    needsConsolidation: false,
+    length: result.length,
+  };
+}
+
+// ─── Consolidation ──────────────────────────────────────────────────────────
+
+/**
+ * Consolidate the user profile using an LLM to stay within character limits.
+ * The LLM merges and summarizes the profile, preserving key preferences.
+ *
+ * @param {function} llmFn - async (prompt) => string — LLM call function
+ * @returns {Promise<{ consolidated: boolean, oldLength: number, newLength: number }>}
+ */
+export async function consolidateUserProfile(llmFn) {
+  const current = readUserProfile();
+  if (!current || current.length <= MAX_PROFILE_LENGTH) {
+    return {
+      consolidated: false,
+      oldLength: current.length,
+      newLength: current.length,
+    };
+  }
+
+  const prompt = `You are consolidating a user profile for an AI assistant. Merge and summarize the following user preferences into a concise profile under ${MAX_PROFILE_LENGTH} characters. Preserve the most important preferences, coding style, and tech stack information. Return ONLY the consolidated profile text, no explanations.\n\n---\n${current}\n---`;
+
+  try {
+    const consolidated = await llmFn(prompt);
+    if (consolidated && typeof consolidated === "string") {
+      const result = updateUserProfile(consolidated);
+      return {
+        consolidated: true,
+        oldLength: current.length,
+        newLength: result.length,
+      };
+    }
+  } catch (_err) {
+    // Consolidation is optional; failure is non-critical
+  }
+
+  return {
+    consolidated: false,
+    oldLength: current.length,
+    newLength: current.length,
+  };
+}
+
+// ─── Exports ────────────────────────────────────────────────────────────────
+
+export const MAX_USER_PROFILE_LENGTH = MAX_PROFILE_LENGTH;

package/src/lib/web-ui-server.js

@@ -571,7 +571,7 @@ function buildHtml({
   const btnQuestionSubmit = $('btn-question-submit');
   const tabBtns = document.querySelectorAll('.tab-btn');
 
-  // ── Init mode badge ─────────────────────────────────────────────────��────
+  // ── Init mode badge ──────────────────────────────────────────────────────
   if (CFG.mode === 'project') {
     modeBadge.innerHTML =
       '<div id="project-badge">' +