wicked-brain 0.4.14 → 0.5.0

package/install.mjs

@@ -126,6 +126,31 @@ if (installHooks) {
   }
 }
 
+// Register as a wicked-bus provider if bus is available
+try {
+  const { openDb, resolveDbPath, register } = await import("wicked-bus");
+  const busDbPath = resolveDbPath();
+  const busDb = openDb(busDbPath);
+  try {
+    register(busDb, {
+      plugin: "wicked-brain",
+      role: "provider",
+      filter: "wicked.*",
+    });
+    console.log("\nwicked-bus: registered wicked-brain as provider");
+  } catch (err) {
+    // Already registered or other non-fatal issue
+    if (err.message && err.message.includes("UNIQUE")) {
+      console.log("\nwicked-bus: wicked-brain already registered as provider");
+    } else {
+      console.log(`\nwicked-bus: could not register (${err.message})`);
+    }
+  }
+  busDb.close();
+} catch {
+  console.log("\nwicked-bus: not available (install wicked-bus to enable event integration)");
+}
+
 // Server binary is bundled — npx wicked-brain-server works automatically
 // Skills reference it as: npx wicked-brain-server --brain {path} --port {port}
 console.log("\nServer: bundled (use 'npx wicked-brain-server' to start)");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wicked-brain",
-  "version": "0.4.14",
+  "version": "0.5.0",
   "type": "module",
   "description": "Digital brain as skills for AI coding CLIs — no vector DB, no embeddings, no infrastructure",
   "keywords": [
@@ -31,7 +31,8 @@
     "wicked-brain-server": "./server/bin/wicked-brain-server.mjs"
   },
   "dependencies": {
-    "better-sqlite3": "^12.0.0"
+    "better-sqlite3": "^12.0.0",
+    "wicked-bus": "^1.0.0"
   },
   "files": [
     "install.mjs",

package/server/bin/wicked-brain-server.mjs

@@ -6,6 +6,7 @@ import { argv, pid, exit } from "node:process";
 import { FileWatcher } from "../lib/file-watcher.mjs";
 import { SqliteSearch } from "../lib/sqlite-search.mjs";
 import { LspClient } from "../lib/lsp-client.mjs";
+import { emitEvent, waitForBus } from "../lib/bus.mjs";
 
 // Parse args
 const args = argv.slice(2);
@@ -88,11 +89,38 @@ process.on("SIGINT", () => shutdown());
 // Action dispatch
 const actions = {
   health: () => db.health(),
-  search: (p) => db.search(p),
-  federated_search: (p) => db.federatedSearch(p),
-  index: (p) => db.index(p),
-  remove: (p) => db.remove(p.id),
-  reindex: (p) => db.reindex(p.docs),
+  search: (p) => {
+    const result = db.search(p);
+    emitEvent("wicked.search.executed", "brain.search", {
+      query: p.query, result_count: result.total_matches, brain_id: brainId,
+    });
+    return result;
+  },
+  federated_search: (p) => {
+    const result = db.federatedSearch(p);
+    emitEvent("wicked.search.executed", "brain.search", {
+      query: p.query, federated: true, brain_id: brainId,
+    });
+    return result;
+  },
+  index: (p) => {
+    db.index(p);
+    emitEvent("wicked.chunk.indexed", "brain.chunk", {
+      id: p.id, path: p.path, brain_id: brainId,
+    });
+  },
+  remove: (p) => {
+    db.remove(p.id);
+    emitEvent("wicked.chunk.removed", "brain.chunk", {
+      id: p.id, brain_id: brainId,
+    });
+  },
+  reindex: (p) => {
+    db.reindex(p.docs);
+    emitEvent("wicked.brain.reindexed", "brain", {
+      doc_count: p.docs.length, brain_id: brainId,
+    });
+  },
   backlinks: (p) => ({ links: db.backlinks(p.id) }),
   forward_links: (p) => ({ links: db.forwardLinks(p.id) }),
   stats: () => db.stats(),
@@ -125,7 +153,13 @@ const actions = {
   access_log: (p) => db.accessLog(p.id),
   recent_memories: (p) => ({ memories: db.recentMemories(p) }),
   contradictions: () => ({ links: db.contradictions() }),
-  confirm_link: (p) => db.confirmLink(p.source_id, p.target_path, p.verdict),
+  confirm_link: (p) => {
+    const result = db.confirmLink(p.source_id, p.target_path, p.verdict);
+    emitEvent("wicked.link.confirmed", "brain.link", {
+      source_id: p.source_id, target_path: p.target_path, verdict: p.verdict, brain_id: brainId,
+    });
+    return result;
+  },
   link_health: () => db.linkHealth(),
   tag_frequency: () => ({ tags: db.tagFrequency() }),
   search_misses: (p) => ({ misses: db.searchMisses(p) }),
@@ -201,7 +235,11 @@ try {
   console.error(`Warning: could not write port to config: ${err.message}`);
 }
 
-server.listen(port, () => {
+server.listen(port, async () => {
   console.log(`wicked-brain-server running on port ${port} (brain: ${brainId}, pid: ${pid})`);
   watcher.start();
+  await waitForBus();
+  emitEvent("wicked.server.started", "brain.system", {
+    brain_id: brainId, port, pid,
+  });
 });

package/server/lib/bus.mjs

@@ -0,0 +1,75 @@
+/**
+ * wicked-bus integration for wicked-brain-server.
+ *
+ * Emits events to the bus when the bus is available.
+ * Degrades gracefully — if wicked-bus is not installed or the DB
+ * is unreachable, events are silently dropped.
+ *
+ * @module lib/bus
+ */
+
+const DOMAIN = "wicked-brain";
+
+let busEmit = null;
+let busDb = null;
+let busConfig = null;
+let available = false;
+
+/**
+ * Try to load wicked-bus at startup. If unavailable, all emit calls are no-ops.
+ */
+async function init() {
+  try {
+    const bus = await import("wicked-bus");
+    busConfig = bus.loadConfig();
+    const dbPath = bus.resolveDbPath();
+    busDb = bus.openDb(dbPath);
+    busEmit = bus.emit;
+    available = true;
+  } catch {
+    // wicked-bus not installed or not initialized — degrade silently
+    available = false;
+  }
+}
+
+// Initialize on module load (non-blocking)
+const ready = init();
+
+/**
+ * Emit an event to the bus.
+ * Fire-and-forget — never throws, never blocks the caller.
+ *
+ * @param {string} eventType - e.g. "wicked.chunk.indexed"
+ * @param {string} subdomain - e.g. "brain.chunk"
+ * @param {object} payload - event-specific data
+ */
+export function emitEvent(eventType, subdomain, payload) {
+  if (!available) return;
+  try {
+    busEmit(busDb, busConfig, {
+      event_type: eventType,
+      domain: DOMAIN,
+      subdomain,
+      payload,
+    });
+  } catch {
+    // Bus emit failed — degrade silently
+  }
+}
+
+/**
+ * Whether the bus is available.
+ * @returns {boolean}
+ */
+export function busAvailable() {
+  return available;
+}
+
+/**
+ * Wait for bus initialization to complete.
+ * Only needed if you must know availability before the first emit.
+ */
+export async function waitForBus() {
+  await ready;
+  return available;
+}

package/server/lib/file-watcher.mjs

@@ -36,26 +36,33 @@ export class FileWatcher {
   }
 
   start() {
+    const brainDirs = ["chunks", "wiki", "memory"];
+
     // Build initial hash map
-    this.#scanAndHash("chunks");
-    this.#scanAndHash("wiki");
-    this.#scanAndHash("memory");
+    for (const dir of brainDirs) this.#scanAndHash(dir);
 
     // Watch directories
-    for (const dir of ["chunks", "wiki", "memory"]) {
-      const absDir = join(this.#brainPath, dir);
-      if (!existsSync(absDir)) continue;
+    const unwatched = [];
+    for (const dir of brainDirs) {
+      if (!this.#tryWatch(dir)) unwatched.push(dir);
+    }
 
-      try {
-        const watcher = watch(absDir, { recursive: true }, (eventType, filename) => {
-          if (!filename || !filename.endsWith(".md")) return;
-          const relPath = normalizePath(`${dir}/${filename}`);
-          this.#debounce(relPath, () => this.#handleChange(relPath));
-        });
-        this.#watchers.push(watcher);
-      } catch {
-        // recursive watch not supported on this platform (Linux) — fall back to polling
-      }
+    // Retry directories that were missing at startup (check every 3s, stop after 30s)
+    if (unwatched.length > 0) {
+      const pending = new Set(unwatched);
+      let elapsed = 0;
+      const retryInterval = setInterval(() => {
+        elapsed += 3000;
+        for (const dir of pending) {
+          if (this.#tryWatch(dir)) {
+            this.#scanAndHash(dir);
+            pending.delete(dir);
+          }
+        }
+        if (pending.size === 0 || elapsed >= 30000) clearInterval(retryInterval);
+      }, 3000);
+      // Don't keep the process alive just for retries
+      retryInterval.unref();
     }
 
     // Watch registered project directories
@@ -84,6 +91,24 @@ export class FileWatcher {
     }
   }
 
+  /** Try to set up fs.watch for a brain subdirectory. Returns true on success. */
+  #tryWatch(dir) {
+    const absDir = join(this.#brainPath, dir);
+    if (!existsSync(absDir)) return false;
+    try {
+      const watcher = watch(absDir, { recursive: true }, (eventType, filename) => {
+        if (!filename || !filename.endsWith(".md")) return;
+        const relPath = normalizePath(`${dir}/${filename}`);
+        this.#debounce(relPath, () => this.#handleChange(relPath));
+      });
+      this.#watchers.push(watcher);
+      return true;
+    } catch {
+      // recursive watch not supported (Linux) — polling fallback handles it
+      return false;
+    }
+  }
+
   stop() {
     for (const w of this.#watchers) w.close();
     this.#watchers = [];

package/server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wicked-brain-server",
-  "version": "0.4.14",
+  "version": "0.5.0",
   "type": "module",
   "description": "SQLite FTS5 search server for wicked-brain digital knowledge bases",
   "keywords": [

package/skills/wicked-brain-agent/SKILL.md

@@ -58,6 +58,30 @@ context or produce incomplete results.
 
 If the host CLI does not support subagent dispatch, fall back to inline execution — run the pipeline steps directly in the current context.
 
+## Bus Events
+
+When dispatching an agent, emit:
+
+```bash
+npx wicked-bus emit \
+  --type "wicked.agent.dispatched" \
+  --domain "wicked-brain" \
+  --subdomain "brain.agent" \
+  --payload '{"agent":"{agent_name}","brain_id":"{brain_id}"}' 2>/dev/null || true
+```
+
+The consolidate agent should also emit `wicked.brain.consolidated` on completion:
+
+```bash
+npx wicked-bus emit \
+  --type "wicked.brain.consolidated" \
+  --domain "wicked-brain" \
+  --subdomain "brain" \
+  --payload '{"brain_id":"{brain_id}","archived":{N},"promoted":{M},"merged":{P}}' 2>/dev/null || true
+```
+
+Fire-and-forget — if the bus is not installed, silently skip.
+
 ## Cross-Platform Notes
 
 - Agent definitions are portable markdown — they work on all platforms

package/skills/wicked-brain-compile/SKILL.md

@@ -215,7 +215,21 @@ Append to `{brain_path}/_meta/log.jsonl` for each article:
 {"ts":"{ISO}","op":"write","path":"{article_path}","author":"llm:compile","content_hash":"{hash}"}
 ```
 
-## Step 7: Report
+## Step 7: Emit bus events
+
+For each article written or updated, emit:
+
+```bash
+npx wicked-bus emit \
+  --type "wicked.article.compiled" \
+  --domain "wicked-brain" \
+  --subdomain "brain.wiki" \
+  --payload '{"path":"{article_path}","brain_id":"{brain_id}","source_chunk_count":{N},"persona":"{synthesis_persona}"}' 2>/dev/null || true
+```
+
+Fire-and-forget — if the bus is not installed, silently skip.
+
+## Step 8: Report
 
 State how many articles were created/updated and what concepts they cover.
 ```

package/skills/wicked-brain-configure/SKILL.md

@@ -105,7 +105,19 @@ Digital brain: {brain_id} | {total} indexed items | {chunks} chunks, {wiki} wiki
 - Capture non-obvious decisions, patterns, and gotchas with `wicked-brain:memory`
 ```
 
-### Step 4: Confirm
+### Step 4: Emit bus event
+
+```bash
+npx wicked-bus emit \
+  --type "wicked.config.updated" \
+  --domain "wicked-brain" \
+  --subdomain "brain.system" \
+  --payload '{"config_file":"{path}","platform":"{detected_platform}","brain_id":"{brain_id}"}' 2>/dev/null || true
+```
+
+Fire-and-forget — if the bus is not installed, silently skip.
+
+### Step 5: Confirm
 
 Report what was written and where:
 - Config file: {path}

package/skills/wicked-brain-enhance/SKILL.md

@@ -137,7 +137,21 @@ Only synthesize connections and summaries from what already exists.}
 Index each new chunk via the server API.
 Append to log.jsonl for each chunk written.
 
-## Step 5: Report
+## Step 5: Emit bus events
+
+For each inferred chunk created, emit:
+
+```bash
+npx wicked-bus emit \
+  --type "wicked.chunk.enhanced" \
+  --domain "wicked-brain" \
+  --subdomain "brain.chunk" \
+  --payload '{"path":"{chunk_path}","brain_id":"{brain_id}","topic":"{topic}","confidence":0.6}' 2>/dev/null || true
+```
+
+Fire-and-forget — if the bus is not installed, silently skip.
+
+## Step 6: Report
 
 State what gaps were identified and how many inferred chunks were created.
 ```

package/skills/wicked-brain-forget/SKILL.md

@@ -88,7 +88,19 @@ Append to `{brain_path}/_meta/log.jsonl`:
 {"ts":"{ISO}","op":"memory_forget","path":"{path}","id":"{id}","mode":"{mode}","reason":"{reason}","author":"agent:forget"}
 ```
 
-### Step 6: Report
+### Step 6: Emit bus event
+
+```bash
+npx wicked-bus emit \
+  --type "wicked.memory.archived" \
+  --domain "wicked-brain" \
+  --subdomain "brain.memory" \
+  --payload '{"path":"{path}","id":"{id}","mode":"{mode}","reason":"{reason}"}' 2>/dev/null || true
+```
+
+Fire-and-forget — if the bus is not installed, silently skip.
+
+### Step 7: Report
 
 Report: path, id, previous frontmatter type/tier (if memory), archive filename,
 and whether index removal succeeded. Always surface the archive path so the

package/skills/wicked-brain-init/SKILL.md

@@ -189,17 +189,18 @@ Use your native Write tool to create these directories (write a `.gitkeep` place
 - `{brain_path}/chunks/inferred`
 - `{brain_path}/wiki/concepts`
 - `{brain_path}/wiki/topics`
+- `{brain_path}/memory`
 - `{brain_path}/_meta`
 
 Shell equivalents if needed:
 ```bash
 # macOS/Linux
 mkdir -p {brain_path}/raw {brain_path}/chunks/extracted {brain_path}/chunks/inferred \
-  {brain_path}/wiki/concepts {brain_path}/wiki/topics {brain_path}/_meta
+  {brain_path}/wiki/concepts {brain_path}/wiki/topics {brain_path}/memory {brain_path}/_meta
 ```
 ```powershell
 # Windows PowerShell
-New-Item -ItemType Directory -Force -Path "{brain_path}\raw","{brain_path}\chunks\extracted","{brain_path}\chunks\inferred","{brain_path}\wiki\concepts","{brain_path}\wiki\topics","{brain_path}\_meta"
+New-Item -ItemType Directory -Force -Path "{brain_path}\raw","{brain_path}\chunks\extracted","{brain_path}\chunks\inferred","{brain_path}\wiki\concepts","{brain_path}\wiki\topics","{brain_path}\memory","{brain_path}\_meta"
 ```
 
 ### Step 4: Write brain.json
@@ -279,7 +280,21 @@ Invoke `wicked-brain:configure` to write routing instructions into the active
 CLI's agent config (CLAUDE.md, GEMINI.md, etc.). This is what makes the brain
 the default for search and exploration — do not skip this step.
 
-### Step 10: Confirm
+### Step 10: Emit bus event
+
+If wicked-bus is available, emit an initialization event:
+
+```bash
+npx wicked-bus emit \
+  --type "wicked.brain.initialized" \
+  --domain "wicked-brain" \
+  --subdomain "brain" \
+  --payload '{"brain_id":"{id}","brain_path":"{brain_path}","name":"{name}"}' 2>/dev/null || true
+```
+
+This is fire-and-forget — if the bus is not installed, the command silently fails.
+
+### Step 11: Confirm
 
 Tell the user:
 "Brain `{name}` is ready at `{brain_path}` — {N} files ingested, {M} chunks indexed.

package/skills/wicked-brain-memory/SKILL.md

@@ -17,7 +17,7 @@ Store and recall experiential learnings in the brain's memory system.
 - Uses `curl` for server API calls (available on Windows 10+, macOS, Linux)
 - File writes use agent-native tools (Write/Edit), not shell commands
 - Path separator: always use forward slashes in `contains:` and `path` fields
-- Brain path default: `~/.wicked-brain` (macOS/Linux), `%USERPROFILE%\.wicked-brain` (Windows)
+- Brain path default: `~/.wicked-brain/projects/{project-name}` (macOS/Linux), `%USERPROFILE%\.wicked-brain\projects\{project-name}` (Windows)
 
 ## Config
 
@@ -154,6 +154,18 @@ Append to `{brain_path}/_meta/log.jsonl`:
 {"ts":"{ISO}","op":"memory_store","path":"memory/{safe_name}.md","type":"{type}","tier":"working","author":"agent:memory"}
 ```
 
+### Step 7: Emit bus event
+
+```bash
+npx wicked-bus emit \
+  --type "wicked.memory.stored" \
+  --domain "wicked-brain" \
+  --subdomain "brain.memory" \
+  --payload '{"path":"memory/{safe_name}.md","type":"{type}","tier":"working","brain_id":"{brain_id}"}' 2>/dev/null || true
+```
+
+Fire-and-forget — if the bus is not installed, silently skip.
+
 ## Recall Mode
 
 ### Progressive loading

package/skills/wicked-brain-migrate/SKILL.md

@@ -246,7 +246,19 @@ Delete the flat `_meta/` directory:
 
 The flat path is now a pure container with only `projects/` beneath it.
 
-### Step 10: Report
+### Step 10: Emit bus event
+
+```bash
+npx wicked-bus emit \
+  --type "wicked.schema.migrated" \
+  --domain "wicked-brain" \
+  --subdomain "brain.system" \
+  --payload '{"from":"{flat_path}","to":"{target_path}","brain_id":"{brain_id}","doc_count":{N}}' 2>/dev/null || true
+```
+
+Fire-and-forget — if the bus is not installed, silently skip.
+
+### Step 11: Report
 
 Tell the user:
 

package/skills/wicked-brain-query/SKILL.md

@@ -177,7 +177,19 @@ Sources:
 - {path}: {one-line description of what it contributed}
 - {path}: {one-line description}
 
-## Step 5: Log search effectiveness
+## Step 5: Emit bus event
+
+```bash
+npx wicked-bus emit \
+  --type "wicked.query.executed" \
+  --domain "wicked-brain" \
+  --subdomain "brain.query" \
+  --payload '{"question":"{question}","sources_found":{count},"brain_id":"{brain_id}"}' 2>/dev/null || true
+```
+
+Fire-and-forget — if the bus is not installed, silently skip.
+
+## Step 6: Log search effectiveness
 
 If evidence was insufficient to answer the question fully, append a
 search-miss event to the brain's log:

package/skills/wicked-brain-retag/SKILL.md

@@ -83,7 +83,21 @@ If **dry_run**: report the file path, current tag count, and proposed new tags.
 
 If not dry_run: update the `contains:` field in the YAML frontmatter in-place using the Edit tool. The server's file watcher will detect the change and re-index.
 
-### Step 5: Summary
+### Step 5: Emit bus event
+
+After all files are updated (not in dry_run mode), emit a single summary event:
+
+```bash
+npx wicked-bus emit \
+  --type "wicked.tag.backfilled" \
+  --domain "wicked-brain" \
+  --subdomain "brain.chunk" \
+  --payload '{"files_updated":{N},"files_scanned":{total},"brain_id":"{brain_id}"}' 2>/dev/null || true
+```
+
+Fire-and-forget — if the bus is not installed, silently skip.
+
+### Step 6: Summary
 
 Report:
 - Total files scanned

package/skills/wicked-brain-synonyms/SKILL.md

@@ -138,3 +138,17 @@ Ask: "Apply all, apply some (specify numbers), or cancel?"
 
 Only write to `synonyms.json` after explicit user approval. Merge approved
 suggestions with any existing entries using the same add-synonym logic above.
+
+## Bus Events
+
+After any write to `synonyms.json` (add, remove, or auto-suggest apply), emit:
+
+```bash
+npx wicked-bus emit \
+  --type "wicked.synonym.updated" \
+  --domain "wicked-brain" \
+  --subdomain "brain.taxonomy" \
+  --payload '{"operation":"{add|remove|auto-apply}","term":"{term}","brain_id":"{brain_id}"}' 2>/dev/null || true
+```
+
+Fire-and-forget — if the bus is not installed, silently skip.