skyloom 1.16.2 → 1.18.0

package/dist/plugins/loader.d.ts

@@ -1,7 +1,36 @@
 /**
- * Plugin loader — loads external plugins that register additional tools.
+ * Plugin loader — discovers external plugins and runs them through an ordered
+ * hook lifecycle.
+ *
+ * A plugin is a directory with an `index.js` exporting either:
+ *   - activate(ctx): the lifecycle form. `ctx` scopes every registration to the
+ *     plugin (registerTool / on(hook, fn)), so unload(name) cleanly removes
+ *     exactly what the plugin added.
+ *   - register(registry): the legacy form. Still supported — tools it adds are
+ *     diffed against the registry so they're tracked for unload too.
+ *
+ * Hooks fire in registration order. Core hooks: `init` (after all plugins
+ * load), `tool.register` (a tool was added), `provider.update` (model/provider
+ * config changed). Plugins may define and emit their own hook names.
  */
-import { ToolRegistry } from '../core/tool';
+import { ToolRegistry, type ToolDefinition } from '../core/tool';
+import { getLogger } from '../core/logger';
+export type PluginHook = 'init' | 'tool.register' | 'provider.update' | string;
+export type HookHandler = (payload?: any) => void | Promise<void>;
+/** Scoped API handed to a plugin's activate(); every call is tracked for unload. */
+export interface PluginContext {
+    readonly name: string;
+    readonly config: any;
+    readonly log: ReturnType<typeof getLogger>;
+    registerTool(def: ToolDefinition): void;
+    on(hook: PluginHook, handler: HookHandler): void;
+}
+export interface Plugin {
+    name?: string;
+    activate?(ctx: PluginContext): void | Promise<void>;
+    register?(registry: ToolRegistry): void;
+    deactivate?(): void | Promise<void>;
+}
 /**
  * A plugin path is safe to `require` only if neither it nor (on POSIX) its
  * permissions allow group/world write — otherwise a less-privileged user could
@@ -11,14 +40,26 @@ import { ToolRegistry } from '../core/tool';
 export declare function isSafePluginPath(target: string): boolean;
 export declare class PluginLoader {
     private toolRegistry;
-    constructor(toolRegistry: ToolRegistry);
-    /**
-     * Load plugins from specified directories.
-     */
+    private config;
+    private plugins;
+    /** hook name -> handlers in registration order, each tagged with its plugin. */
+    private hookHandlers;
+    constructor(toolRegistry: ToolRegistry, config?: any);
+    /** Load plugins from specified directories. Returns the number activated. */
     loadFromDirectories(directories: string[]): number;
+    private loadDirectory;
     /**
-     * Load a single plugin directory.
+     * Activate a plugin module under a name. Reactivating an already-loaded name
+     * unloads the previous instance first. Returns true if anything registered.
      */
-    private loadDirectory;
+    activatePlugin(name: string, mod: Plugin): boolean;
+    /** Fire a hook; handlers run in registration order. Errors are isolated. */
+    emit(hook: PluginHook, payload?: any): Promise<void>;
+    /** Unload a plugin: remove its tools and hook handlers, call deactivate. */
+    unload(name: string): boolean;
+    /** Names of currently loaded plugins. */
+    list(): string[];
+    /** Number of handlers registered for a hook (for diagnostics/tests). */
+    hookCount(hook: PluginHook): number;
 }
 //# sourceMappingURL=loader.d.ts.map

package/dist/plugins/loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../src/plugins/loader.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAK5C;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CASxD;AAED,qBAAa,YAAY;IACvB,OAAO,CAAC,YAAY,CAAe;gBAEvB,YAAY,EAAE,YAAY;IAItC;;OAEG;IACH,mBAAmB,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,MAAM;IAQlD;;OAEG;IACH,OAAO,CAAC,aAAa;CAyCtB"}
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../src/plugins/loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,OAAO,EAAE,YAAY,EAAE,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AACjE,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAI3C,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,eAAe,GAAG,iBAAiB,GAAG,MAAM,CAAC;AAC/E,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,CAAC,EAAE,GAAG,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAElE,oFAAoF;AACpF,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,GAAG,CAAC;IACrB,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAC,OAAO,SAAS,CAAC,CAAC;IAC3C,YAAY,CAAC,GAAG,EAAE,cAAc,GAAG,IAAI,CAAC;IACxC,EAAE,CAAC,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,WAAW,GAAG,IAAI,CAAC;CAClD;AAED,MAAM,WAAW,MAAM;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,CAAC,GAAG,EAAE,aAAa,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpD,QAAQ,CAAC,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI,CAAC;IACxC,UAAU,CAAC,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACrC;AASD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CASxD;AAED,qBAAa,YAAY;IACvB,OAAO,CAAC,YAAY,CAAe;IACnC,OAAO,CAAC,MAAM,CAAM;IACpB,OAAO,CAAC,OAAO,CAAmC;IAClD,gFAAgF;IAChF,OAAO,CAAC,YAAY,CAAiE;gBAEzE,YAAY,EAAE,YAAY,EAAE,MAAM,CAAC,EAAE,GAAG;IAKpD,6EAA6E;IAC7E,mBAAmB,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,MAAM;IAQlD,OAAO,CAAC,aAAa;IAqCrB;;;OAGG;IACH,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO;IAqDlD,4EAA4E;IACtE,IAAI,CAAC,IAAI,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;IAY1D,4EAA4E;IAC5E,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAiB7B,yCAAyC;IACzC,IAAI,IAAI,MAAM,EAAE;IAEhB,wEAAwE;IACxE,SAAS,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM;CACpC"}

package/dist/plugins/loader.js

@@ -1,6 +1,18 @@
 "use strict";
 /**
- * Plugin loader — loads external plugins that register additional tools.
+ * Plugin loader — discovers external plugins and runs them through an ordered
+ * hook lifecycle.
+ *
+ * A plugin is a directory with an `index.js` exporting either:
+ *   - activate(ctx): the lifecycle form. `ctx` scopes every registration to the
+ *     plugin (registerTool / on(hook, fn)), so unload(name) cleanly removes
+ *     exactly what the plugin added.
+ *   - register(registry): the legacy form. Still supported — tools it adds are
+ *     diffed against the registry so they're tracked for unload too.
+ *
+ * Hooks fire in registration order. Core hooks: `init` (after all plugins
+ * load), `tool.register` (a tool was added), `provider.update` (model/provider
+ * config changed). Plugins may define and emit their own hook names.
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
@@ -62,12 +74,14 @@ function isSafePluginPath(target) {
     }
 }
 class PluginLoader {
-    constructor(toolRegistry) {
+    constructor(toolRegistry, config) {
+        this.plugins = new Map();
+        /** hook name -> handlers in registration order, each tagged with its plugin. */
+        this.hookHandlers = new Map();
         this.toolRegistry = toolRegistry;
+        this.config = config ?? {};
     }
-    /**
-     * Load plugins from specified directories.
-     */
+    /** Load plugins from specified directories. Returns the number activated. */
     loadFromDirectories(directories) {
         let total = 0;
         for (const dir of directories) {
@@ -75,9 +89,6 @@ class PluginLoader {
         }
         return total;
     }
-    /**
-     * Load a single plugin directory.
-     */
     loadDirectory(dir) {
         if (!fs.existsSync(dir)) {
             log.debug('plugin_dir_not_found', { dir });
@@ -85,11 +96,15 @@ class PluginLoader {
         }
         let count = 0;
         try {
-            const entries = fs.readdirSync(dir);
-            for (const entry of entries) {
+            for (const entry of fs.readdirSync(dir)) {
                 const pluginPath = path.join(dir, entry);
-                if (!fs.statSync(pluginPath).isDirectory())
+                try {
+                    if (!fs.statSync(pluginPath).isDirectory())
+                        continue;
+                }
+                catch {
                     continue;
+                }
                 const pluginFile = path.join(pluginPath, 'index.js');
                 if (!fs.existsSync(pluginFile))
                     continue;
@@ -101,12 +116,9 @@ class PluginLoader {
                     continue;
                 }
                 try {
-                    const plugin = require(pluginFile);
-                    if (typeof plugin.register === 'function') {
-                        plugin.register(this.toolRegistry);
+                    const mod = require(pluginFile);
+                    if (this.activatePlugin(entry, mod))
                         count++;
-                        log.info('plugin_loaded', { name: entry });
-                    }
                 }
                 catch (e) {
                     log.warn('plugin_load_failed', { name: entry, error: String(e) });
@@ -118,6 +130,107 @@ class PluginLoader {
         }
         return count;
     }
+    /**
+     * Activate a plugin module under a name. Reactivating an already-loaded name
+     * unloads the previous instance first. Returns true if anything registered.
+     */
+    activatePlugin(name, mod) {
+        const pluginName = mod.name || name;
+        if (this.plugins.has(pluginName))
+            this.unload(pluginName);
+        const record = { name: pluginName, module: mod, tools: [], hooks: [] };
+        const self = this;
+        if (typeof mod.activate === 'function') {
+            const ctx = {
+                name: pluginName,
+                config: this.config,
+                log: (0, logger_1.getLogger)(`plugin:${pluginName}`),
+                registerTool(def) {
+                    self.toolRegistry.register(def);
+                    record.tools.push(def.name);
+                    void self.emit('tool.register', { plugin: pluginName, tool: def.name });
+                },
+                on(hook, handler) {
+                    record.hooks.push({ hook, fn: handler });
+                    const arr = self.hookHandlers.get(hook) || [];
+                    arr.push({ plugin: pluginName, fn: handler });
+                    self.hookHandlers.set(hook, arr);
+                },
+            };
+            try {
+                void mod.activate(ctx);
+            }
+            catch (e) {
+                log.warn('plugin_activate_failed', { name: pluginName, error: String(e) });
+                this.unload(pluginName);
+                return false;
+            }
+        }
+        else if (typeof mod.register === 'function') {
+            // Legacy: diff the registry to learn which tools the plugin added.
+            const before = new Set(this.toolRegistry.listNames());
+            try {
+                mod.register(this.toolRegistry);
+            }
+            catch (e) {
+                log.warn('plugin_register_failed', { name: pluginName, error: String(e) });
+                return false;
+            }
+            for (const n of this.toolRegistry.listNames()) {
+                if (!before.has(n))
+                    record.tools.push(n);
+            }
+        }
+        else {
+            log.warn('plugin_no_entrypoint', { name: pluginName });
+            return false;
+        }
+        this.plugins.set(pluginName, record);
+        log.info('plugin_loaded', { name: pluginName, tools: record.tools.length, hooks: record.hooks.length });
+        return true;
+    }
+    /** Fire a hook; handlers run in registration order. Errors are isolated. */
+    async emit(hook, payload) {
+        const handlers = this.hookHandlers.get(hook);
+        if (!handlers || handlers.length === 0)
+            return;
+        for (const { plugin, fn } of [...handlers]) {
+            try {
+                await fn(payload);
+            }
+            catch (e) {
+                log.warn('plugin_hook_failed', { hook, plugin, error: String(e) });
+            }
+        }
+    }
+    /** Unload a plugin: remove its tools and hook handlers, call deactivate. */
+    unload(name) {
+        const record = this.plugins.get(name);
+        if (!record)
+            return false;
+        for (const tool of record.tools)
+            this.toolRegistry.unregister(tool);
+        for (const [hook, arr] of this.hookHandlers) {
+            const filtered = arr.filter((h) => h.plugin !== name);
+            if (filtered.length)
+                this.hookHandlers.set(hook, filtered);
+            else
+                this.hookHandlers.delete(hook);
+        }
+        try {
+            record.module.deactivate?.();
+        }
+        catch (e) {
+            log.warn('plugin_deactivate_failed', { name, error: String(e) });
+        }
+        this.plugins.delete(name);
+        log.info('plugin_unloaded', { name });
+        return true;
+    }
+    /** Names of currently loaded plugins. */
+    list() { return [...this.plugins.keys()]; }
+    /** Number of handlers registered for a hook (for diagnostics/tests). */
+    hookCount(hook) { return this.hookHandlers.get(hook)?.length ?? 0; }
 }
 exports.PluginLoader = PluginLoader;
 //# sourceMappingURL=loader.js.map

package/dist/plugins/loader.js.map

@@ -1 +1 @@
-{"version":3,"file":"loader.js","sourceRoot":"","sources":["../../src/plugins/loader.ts"],"names":[],"mappings":";AAAA;;GAEG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAeH,4CASC;AAtBD,uCAAyB;AACzB,2CAA6B;AAE7B,2CAA2C;AAE3C,MAAM,GAAG,GAAG,IAAA,kBAAS,EAAC,eAAe,CAAC,CAAC;AAEvC;;;;;GAKG;AACH,SAAgB,gBAAgB,CAAC,MAAc;IAC7C,IAAI,OAAO,CAAC,GAAG,CAAC,4BAA4B,KAAK,GAAG;QAAE,OAAO,IAAI,CAAC;IAClE,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO;QAAE,OAAO,IAAI,CAAC;IAC9C,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC;QACtC,OAAO,CAAC,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,iCAAiC;IAChE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,MAAa,YAAY;IAGvB,YAAY,YAA0B;QACpC,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;IACnC,CAAC;IAED;;OAEG;IACH,mBAAmB,CAAC,WAAqB;QACvC,IAAI,KAAK,GAAG,CAAC,CAAC;QACd,KAAK,MAAM,GAAG,IAAI,WAAW,EAAE,CAAC;YAC9B,KAAK,IAAI,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC;QACnC,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;OAEG;IACK,aAAa,CAAC,GAAW;QAC/B,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YACxB,GAAG,CAAC,KAAK,CAAC,sBAAsB,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;YAC3C,OAAO,CAAC,CAAC;QACX,CAAC;QAED,IAAI,KAAK,GAAG,CAAC,CAAC;QACd,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,EAAE,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;YACpC,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;gBAC5B,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;gBACzC,IAAI,CAAC,EAAE,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC,WAAW,EAAE;oBAAE,SAAS;gBAErD,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC;gBACrD,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,UAAU,CAAC;oBAAE,SAAS;gBAEzC,wEAAwE;gBACxE,kEAAkE;gBAClE,0EAA0E;gBAC1E,IAAI,CAAC,gBAAgB,CAAC,UAAU,CAAC,IAAI,CAAC,gBAAgB,CAAC,UAAU,CAAC,EAAE,CAAC;oBACnE,GAAG,CAAC,IAAI,CAAC,6BAA6B,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;oBACzD,SAAS;gBACX,CAAC;gBAED,IAAI,CAAC;oBACH,MAAM,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;oBACnC,IAAI,OAAO,MAAM,CAAC,QAAQ,KAAK,UAAU,EAAE,CAAC;wBAC1C,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;wBACnC,KAAK,EAAE,CAAC;wBACR,GAAG,CAAC,IAAI,CAAC,eAAe,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;oBAC7C,CAAC;gBACH,CAAC;gBAAC,OAAO,CAAC,EAAE,CAAC;oBACX,GAAG,CAAC,IAAI,CAAC,oBAAoB,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;gBACpE,CAAC;YACH,CAAC;QACH,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,GAAG,CAAC,IAAI,CAAC,wBAAwB,EAAE,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QAChE,CAAC;QAED,OAAO,KAAK,CAAC;IACf,CAAC;CACF;AA9DD,oCA8DC"}
+{"version":3,"file":"loader.js","sourceRoot":"","sources":["../../src/plugins/loader.ts"],"names":[],"mappings":"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"}

package/dist/tools/builtin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"builtin.d.ts","sourceRoot":"","sources":["../../src/tools/builtin.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAIjD,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAIlF,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,SAAS,EAAE,UAAU,EAAE,CAAC;AAIlE;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI,CAgajE;AAID,wBAAsB,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC,CAKrD"}
+{"version":3,"file":"builtin.d.ts","sourceRoot":"","sources":["../../src/tools/builtin.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAIjD,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAQlF,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,SAAS,EAAE,UAAU,EAAE,CAAC;AAIlE;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI,CAkjBjE;AAID,wBAAsB,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC,CAKrD"}

package/dist/tools/builtin.js

@@ -50,6 +50,10 @@ Object.defineProperty(exports, "assertFetchAllowed", { enumerable: true, get: fu
 Object.defineProperty(exports, "fenceRoot", { enumerable: true, get: function () { return guards_1.fenceRoot; } });
 Object.defineProperty(exports, "fenceCheck", { enumerable: true, get: function () { return guards_1.fenceCheck; } });
 const websearch_1 = require("./websearch");
+const diff_1 = require("../core/diff");
+const diagnostics_1 = require("../core/diagnostics");
+const search_1 = require("../core/search");
+const patch_1 = require("../core/patch");
 const log = (0, logger_1.getLogger)('builtin-tools');
 /**
  * Register all built-in tools into the given registry.
@@ -116,11 +120,12 @@ function registerBuiltinTools(registry) {
     });
     registry.register({
         name: 'edit_file',
-        description: 'Edit a file by replacing old_text with new_text. Use this for targeted edits.',
+        description: 'Edit a file by replacing an exact occurrence of old_text with new_text. old_text must match the file exactly (including whitespace and indentation) and must be UNIQUE — include enough surrounding context to disambiguate, or set replace_all to change every occurrence. Returns a unified diff of the change.',
         parameters: [
             { name: 'path', type: 'string', description: 'Path to the file to edit', required: true },
-            { name: 'old_text', type: 'string', description: 'Text to search for and replace', required: true },
-            { name: 'new_text', type: 'string', description: 'Text to replace with', required: true },
+            { name: 'old_text', type: 'string', description: 'Exact text to replace (must match the file verbatim, and be unique unless replace_all is set)', required: true },
+            { name: 'new_text', type: 'string', description: 'Replacement text (must differ from old_text)', required: true },
+            { name: 'replace_all', type: 'boolean', description: 'Replace every occurrence instead of requiring a unique match (default false)', required: false },
         ],
         handler: async (params) => {
             const filePath = path.resolve(params.path);
@@ -129,22 +134,94 @@ function registerBuiltinTools(registry) {
                 return fenced;
             if (!fs.existsSync(filePath))
                 return `Error: File not found: ${filePath}`;
+            const oldText = params.old_text;
+            const newText = params.new_text;
+            const replaceAll = params.replace_all === true || params.replace_all === 'true';
+            if (oldText === newText)
+                return 'Error: old_text and new_text are identical — nothing to change.';
             try {
-                let content = fs.readFileSync(filePath, 'utf-8');
-                const oldText = params.old_text;
-                const newText = params.new_text;
-                if (!content.includes(oldText)) {
-                    return `Error: old_text not found in file. Searched for: ${oldText.slice(0, 50)}...`;
+                const orig = fs.readFileSync(filePath, 'utf-8');
+                const n = (0, diff_1.countOccurrences)(orig, oldText);
+                if (n === 0) {
+                    return `Error: old_text not found in ${filePath}. It must match exactly (including whitespace). Searched for: ${JSON.stringify(oldText.slice(0, 80))}`;
                 }
-                content = content.replace(oldText, newText);
-                fs.writeFileSync(filePath, content, 'utf-8');
-                return `Successfully edited ${filePath}`;
+                if (n > 1 && !replaceAll) {
+                    return `Error: old_text appears ${n} times in ${filePath} — the edit is ambiguous. Add more surrounding context to make it unique, or set replace_all=true to change all ${n} occurrences.`;
+                }
+                // Literal replacement: split/join (replace_all) and a function replacer
+                // (single) both avoid String.replace interpreting `$&`/`$1` in new_text.
+                const updated = replaceAll
+                    ? orig.split(oldText).join(newText)
+                    : orig.replace(oldText, () => newText);
+                fs.writeFileSync(filePath, updated, 'utf-8');
+                const rel = path.relative(process.cwd(), filePath) || filePath;
+                const diff = (0, diff_1.unifiedDiff)(orig, updated, { path: rel, context: 3 });
+                const occ = replaceAll ? ` (${n} occurrence${n > 1 ? 's' : ''})` : '';
+                const body = diff.text ? `\n${diff.text}` : '';
+                return `Successfully edited ${filePath}${occ} · +${diff.stat.added} -${diff.stat.removed}${body}`;
             }
             catch (e) {
                 return `Error editing file: ${e}`;
             }
         },
     });
+    registry.register({
+        name: 'get_diagnostics',
+        idempotent: true,
+        description: 'Get LSP-style diagnostics (type errors, lint issues with line:col) for a source file. TS/JS work out of the box via the workspace TypeScript; other languages use a configured checker (config.yaml diagnostics map). Call this after editing code to confirm it is error-free, or to locate the root cause of a type error.',
+        parameters: [
+            { name: 'path', type: 'string', description: 'Path to the source file to check', required: true },
+        ],
+        handler: async (params) => {
+            const filePath = path.resolve(params.path);
+            const fenced = (0, guards_1.fenceCheck)(filePath);
+            if (fenced)
+                return fenced;
+            let config = {};
+            try {
+                const { loadConfig } = require('../core/config');
+                config = loadConfig();
+            }
+            catch { /* defaults */ }
+            try {
+                const result = (0, diagnostics_1.getDiagnostics)(filePath, config);
+                if (!Array.isArray(result))
+                    return `[diagnostics unavailable] ${result.unavailable}`;
+                return (0, diagnostics_1.formatDiagnostics)(path.relative(process.cwd(), filePath) || filePath, result);
+            }
+            catch (e) {
+                return `Error getting diagnostics: ${e}`;
+            }
+        },
+    });
+    registry.register({
+        name: 'apply_patch',
+        description: 'Apply an atomic, multi-file edit in one call — ideal for larger refactors touching several places/files. The whole patch is validated before anything is written, so a bad block aborts cleanly with no half-applied changes. Each SEARCH must match the file exactly and uniquely. Format:\n*** Update File: path\n<<<<<<< SEARCH\nold exact text\n=======\nnew text\n>>>>>>> REPLACE\n(repeat blocks; also *** Add File: path / full content, and *** Delete File: path)',
+        parameters: [
+            { name: 'patch', type: 'string', description: 'The patch text in the *** Update/Add/Delete File + SEARCH/REPLACE format', required: true },
+        ],
+        handler: async (params) => {
+            let snapshot;
+            try {
+                const { getFileCheckpoints } = require('../core/file_checkpoint');
+                const cp = getFileCheckpoints();
+                snapshot = (abs) => { try {
+                    cp.snapshot(abs);
+                }
+                catch { /* best-effort */ } };
+            }
+            catch { /* checkpointing optional */ }
+            try {
+                return (0, patch_1.applyPatch)(String(params.patch || ''), {
+                    fenceCheck: (abs) => (0, guards_1.fenceCheck)(abs),
+                    snapshot,
+                });
+            }
+            catch (e) {
+                return `Error applying patch: ${e}`;
+            }
+        },
+    });
     registry.register({
         name: 'delete_file',
         description: 'Delete a file at the given path.',
@@ -222,13 +299,27 @@ function registerBuiltinTools(registry) {
     // ── Shell Tool ──
     registry.register({
         name: 'run_bash',
-        description: 'Execute a shell command and return its output.',
+        description: 'Execute a shell command and return its output. Set background=true for long-running processes (dev servers, watchers, builds): it returns a job id immediately — read its output later with bash_output, stop it with kill_bash.',
         parameters: [
             { name: 'command', type: 'string', description: 'Command to execute', required: true },
-            { name: 'timeout', type: 'number', description: 'Timeout in milliseconds (default: 30000)', required: false },
+            { name: 'timeout', type: 'number', description: 'Timeout in milliseconds (default: 30000). Ignored when background=true.', required: false },
+            { name: 'background', type: 'boolean', description: 'Run detached in the background and return a job id instead of blocking (default false)', required: false },
         ],
         handler: async (params) => {
             const cmd = params.command;
+            const background = params.background === true || params.background === 'true';
+            if (background) {
+                try {
+                    const { getBackgroundManager } = require('../core/bgproc');
+                    const { id, error } = getBackgroundManager().start(cmd);
+                    if (error)
+                        return error;
+                    return `[background job ${id} started] pid running. Use bash_output("${id}") to read output, kill_bash("${id}") to stop, list_bash to see all jobs.`;
+                }
+                catch (e) {
+                    return `Error: ${e.message || e}`;
+                }
+            }
             const timeout = params.timeout || 30000;
             try {
                 const { runInSandbox, formatSandboxResult } = require('../core/sandbox');
@@ -241,6 +332,50 @@ function registerBuiltinTools(registry) {
         },
         dangerous: true,
     });
+    registry.register({
+        name: 'bash_output',
+        description: 'Read new output from a background shell job (started by run_bash with background=true) since the last read, plus its current status.',
+        parameters: [
+            { name: 'id', type: 'string', description: 'The background job id', required: true },
+        ],
+        handler: async (params) => {
+            const { getBackgroundManager } = require('../core/bgproc');
+            const r = getBackgroundManager().read(String(params.id || ''));
+            if (!r.ok)
+                return r.error || 'Error reading background job.';
+            const statusLine = `[job ${params.id} · ${r.status}${r.exitCode != null ? ` · exit ${r.exitCode}` : ''}]`;
+            const out = r.text && r.text.length ? r.text : '(no new output)';
+            return `${statusLine}\n${out}`;
+        },
+    });
+    registry.register({
+        name: 'list_bash',
+        description: 'List background shell jobs with their status, pid, and runtime.',
+        parameters: [],
+        handler: async () => {
+            const { getBackgroundManager } = require('../core/bgproc');
+            const jobs = getBackgroundManager().list();
+            if (!jobs.length)
+                return 'No background jobs.';
+            return jobs.map((j) => {
+                const dur = ((j.endedAt || Date.now()) - j.startedAt) / 1000;
+                const ex = j.exitCode != null ? ` exit ${j.exitCode}` : '';
+                return `${j.id} · ${j.status}${ex} · pid ${j.pid ?? '?'} · ${dur.toFixed(1)}s · ${j.command.slice(0, 60)}`;
+            }).join('\n');
+        },
+    });
+    registry.register({
+        name: 'kill_bash',
+        description: 'Terminate a running background shell job.',
+        parameters: [
+            { name: 'id', type: 'string', description: 'The background job id to kill', required: true },
+        ],
+        handler: async (params) => {
+            const { getBackgroundManager } = require('../core/bgproc');
+            const r = getBackgroundManager().kill(String(params.id || ''));
+            return r.ok ? `[job ${params.id} killed]` : (r.error || 'Error killing background job.');
+        },
+    });
     // ── HTTP Tools ──
     registry.register({
         name: 'http_get',
@@ -419,10 +554,40 @@ function registerBuiltinTools(registry) {
         dangerous: true,
     });
     // ── Utility Tools ──
+    registry.register({
+        name: 'code_search',
+        idempotent: true,
+        description: 'Search source code for a regex pattern across files. Returns file:line matches with optional surrounding context. Use this to find where a symbol/string is defined or used. Restrict scope with glob (e.g. "**/*.ts") and add context lines to read around hits.',
+        parameters: [
+            { name: 'pattern', type: 'string', description: 'Regex (or literal if regex=false) to search for', required: true },
+            { name: 'path', type: 'string', description: 'Root directory to search (default: cwd)', required: false },
+            { name: 'glob', type: 'string', description: 'Restrict to files matching this glob, e.g. "**/*.ts"', required: false },
+            { name: 'context', type: 'number', description: 'Lines of context around each match (default 0)', required: false },
+            { name: 'ignore_case', type: 'boolean', description: 'Case-insensitive match (default false)', required: false },
+            { name: 'regex', type: 'boolean', description: 'Treat pattern as regex (default true; false = literal substring)', required: false },
+            { name: 'max_results', type: 'number', description: 'Max matches to return (default 200)', required: false },
+        ],
+        handler: async (params) => {
+            const root = params.path ? path.resolve(params.path) : process.cwd();
+            const fenced = (0, guards_1.fenceCheck)(root);
+            if (fenced)
+                return fenced;
+            const res = (0, search_1.searchCode)({
+                pattern: String(params.pattern || ''),
+                root,
+                glob: params.glob ? String(params.glob) : undefined,
+                context: params.context != null ? Number(params.context) : 0,
+                ignoreCase: params.ignore_case === true,
+                regex: params.regex !== false,
+                maxResults: params.max_results != null ? Number(params.max_results) : 200,
+            });
+            return (0, search_1.formatSearchResult)(res);
+        },
+    });
     registry.register({
         name: 'grep',
         idempotent: true,
-        description: 'Search for a pattern in files using ripgrep or grep.',
+        description: 'Search for a regex pattern in files using ripgrep/grep, with a built-in fallback when neither is installed. For richer control (glob, context, ignore-case) prefer code_search.',
         parameters: [
             { name: 'pattern', type: 'string', description: 'Regex pattern to search for', required: true },
             { name: 'path', type: 'string', description: 'Directory to search in', required: false },
@@ -448,13 +613,14 @@ function registerBuiltinTools(registry) {
                     return out || 'No matches found.';
                 }
                 catch (e) {
-                    // exit status 1 = ran successfully, zero matches; anything else
-                    // (e.g. binary not installed) falls through to the next variant.
+                    // exit status 1 = ran successfully, zero matches. Any other failure
+                    // (e.g. binary not installed) falls through to the next variant, then
+                    // to the pure-JS engine so search works even with no rg/grep.
                     if (e?.status === 1)
                         return 'No matches found.';
                 }
             }
-            return 'No matches found.';
+            return (0, search_1.formatSearchResult)((0, search_1.searchCode)({ pattern: pat, root: searchDir, maxResults: 200 }));
         },
     });
     registry.register({