pi-vault-mind 0.7.0

package/dist/src/watcher.js

@@ -0,0 +1,411 @@
+/**
+ * Vault Watcher — passive file-system observer for @agent markers.
+ *
+ * Inspired by pi-piqo but redesigned for the pi-vault-mind multi-agent
+ * architecture. Instead of sending prompts directly to the LLM, the
+ * Watcher groups markers by target agent role and dispatches them as
+ * well-structured subagent tasks into the active pi session. The
+ * Manager agent then uses the standard subagent() tool to fork
+ * isolated worker sessions.
+ *
+ * Key differences from pi-piqo:
+ * - Multi-role grouping (one bundled task per agent per file)
+ * - Named IDs force isolation (e.g., @agent-Miner:customId)
+ * - Concurrency limits prevent explosion of subagent processes
+ * - Debounced watching (1000ms per file) groups rapid saves
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+// ── Constants ────────────────────────────────────────────────────────────────────
+const MARKER_REGEX = /@agent-(\w+)(?::(\S+))?\s*(.*)/;
+const WRITEBACK_MARKER_REGEX = /<!--\s*pi-dispatch:(\S+)\s*-->/;
+const DEBOUNCE_MS = 1000;
+const MAX_CONCURRENT = 3;
+const CONTEXT_LINES = 15;
+const WATCHED_EXTENSIONS = new Set([
+    ".txt",
+    ".md",
+    ".markdown",
+    ".mdx",
+    ".js",
+    ".ts",
+    ".jsx",
+    ".tsx",
+    ".py",
+    ".rb",
+    ".rs",
+    ".go",
+    ".java",
+    ".c",
+    ".cpp",
+    ".h",
+    ".hpp",
+    ".css",
+    ".html",
+    ".xml",
+    ".json",
+    ".yaml",
+    ".yml",
+    ".toml",
+    ".sh",
+    ".bash",
+    ".zsh",
+    ".sql",
+    ".r",
+    ".swift",
+    ".kt",
+    ".lua",
+    ".vim",
+    ".el",
+    ".clj",
+    ".hs",
+    ".ml",
+    ".ex",
+    ".exs",
+    ".erl",
+    ".dart",
+    ".cs",
+    ".php",
+    ".pl",
+    ".pm",
+    ".svelte",
+    ".vue",
+    ".astro",
+]);
+const IGNORE_DIRS = new Set([
+    ".git",
+    ".obsidian",
+    "node_modules",
+    ".trash",
+    "__pycache__",
+    ".DS_Store",
+    ".pi",
+    ".lancedb",
+]);
+// ── Helper Functions ─────────────────────────────────────────────────────────────
+function isWatchableFile(filePath) {
+    const ext = path.extname(filePath).toLowerCase();
+    if (!WATCHED_EXTENSIONS.has(ext))
+        return false;
+    const dirParts = filePath.split(path.sep);
+    for (const part of dirParts) {
+        if (IGNORE_DIRS.has(part))
+            return false;
+    }
+    return true;
+}
+/**
+ * Scan a file for @agent markers and return grouped tasks.
+ * Exported for testing.
+ *
+ * Grouping strategy:
+ * 1. Same role markers in a single file are bundled into one task.
+ * 2. Different role markers create separate groups.
+ * 3. Named IDs (e.g., @agent-Miner:customId) force isolation regardless of role.
+ */
+export function scanFile(filePath) {
+    let content;
+    try {
+        content = fs.readFileSync(filePath, "utf-8");
+    }
+    catch {
+        return [];
+    }
+    const lines = content.split("\n");
+    const markers = [];
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const match = line.match(MARKER_REGEX);
+        if (!match)
+            continue;
+        const role = match[1].toLowerCase();
+        const taskId = match[2] || undefined;
+        const instruction = match[3]?.trim() || "";
+        // Build context: surrounding lines
+        const contextStart = Math.max(0, i - CONTEXT_LINES);
+        const contextEnd = Math.min(lines.length, i + CONTEXT_LINES + 1);
+        const contextLines = lines.slice(contextStart, contextEnd);
+        const context = contextLines.map((l, idx) => `${contextStart + idx + 1}: ${l}`).join("\n");
+        markers.push({
+            rawLine: line,
+            lineNumber: i + 1,
+            role,
+            taskId,
+            instruction,
+            context,
+        });
+    }
+    if (markers.length === 0)
+        return [];
+    // Group markers by (role, taskId) pair
+    const groupMap = new Map();
+    for (const marker of markers) {
+        // Named IDs always get their own group; unnamed share by role
+        const groupKey = marker.taskId ? `${marker.role}:${marker.taskId}` : marker.role;
+        if (!groupMap.has(groupKey)) {
+            groupMap.set(groupKey, []);
+        }
+        groupMap.get(groupKey)?.push(marker);
+    }
+    const groups = [];
+    for (const [groupKey, groupMarkers] of groupMap.entries()) {
+        const firstMarker = groupMarkers[0];
+        const role = firstMarker.role;
+        const taskId = firstMarker.taskId || groupKey;
+        // Combine instructions
+        const instructions = groupMarkers
+            .map((m) => `@line ${m.lineNumber}: ${m.instruction}`)
+            .join("\n");
+        const combinedInstruction = [
+            `File: ${filePath}`,
+            `Role: ${role}`,
+            groupMarkers.length > 1 ? `Multiple markers (${groupMarkers.length}):` : "Single marker:",
+            "",
+            instructions,
+            "",
+            "Context:",
+            "```",
+            groupMarkers.map((m) => m.context).join("\n---\n"),
+            "```",
+        ].join("\n");
+        groups.push({
+            role,
+            taskId,
+            markers: groupMarkers,
+            filePath,
+            combinedInstruction,
+            dispatchId: generateDispatchId(role),
+        });
+    }
+    return groups;
+}
+/**
+ * Generate a unique dispatch ID for tracking and writeback targeting.
+ * Exported for testing.
+ */
+export function generateDispatchId(role) {
+    const ts = Date.now();
+    const rand = Math.random().toString(36).slice(2, 8);
+    return `${role}-${ts}-${rand}`;
+}
+/**
+ * Replace @agent markers in the file with a dispatch marker comment.
+ * The comment embeds the dispatch ID so the subagent can find and replace it
+ * with results when it completes.
+ */
+function markProcessing(filePath, groups, dispatchRecords) {
+    try {
+        let content = fs.readFileSync(filePath, "utf-8");
+        for (const group of groups) {
+            const indicator = `<!-- pi-dispatch:${group.dispatchId} -->`;
+            // Replace all markers in this group with the same dispatch indicator
+            for (const marker of group.markers) {
+                content = content.replace(marker.rawLine, indicator);
+            }
+            // Store the dispatch record for status tracking
+            dispatchRecords.set(group.dispatchId, {
+                dispatchId: group.dispatchId,
+                filePath,
+                role: group.role,
+                agentName: group.role, // will be set later in dispatchGroup
+                dispatchedAt: new Date().toISOString(),
+                markerCount: group.markers.length,
+            });
+        }
+        fs.writeFileSync(filePath, content, "utf-8");
+    }
+    catch {
+        // Best-effort; don't block processing
+    }
+}
+// ── Core Watcher Logic ────────────────────────────────────────────────────────────
+export function startWatcher(pi, vaults, state) {
+    if (state.running) {
+        pi.events?.emit?.("wiki:log", { level: "warn", message: "Watcher already running." });
+        return;
+    }
+    state.running = true;
+    const vaultEntries = Object.entries(vaults);
+    if (vaultEntries.length === 0) {
+        console.warn("[pi-vault-mind] No vaults configured. Watcher requires at least one vault in wiki.vaults.");
+        return;
+    }
+    for (const [name, vault] of vaultEntries) {
+        const vaultPath = vault.path;
+        if (!fs.existsSync(vaultPath)) {
+            console.warn(`[pi-vault-mind] Vault "${name}" path does not exist: ${vaultPath}`);
+            continue;
+        }
+        console.log(`[pi-vault-mind] Watching vault "${name}" at ${vaultPath}`);
+        const watcher = fs.watch(vaultPath, { recursive: true }, (eventType, filename) => {
+            if (!filename || !state.running)
+                return;
+            const filePath = path.join(vaultPath, filename);
+            // Skip non-watchable files
+            if (!isWatchableFile(filePath))
+                return;
+            if (!fs.existsSync(filePath))
+                return;
+            // Debounce: clear existing timer, set a new one
+            const existingTimer = state.debounceTimers.get(filePath);
+            if (existingTimer)
+                clearTimeout(existingTimer);
+            const timer = setTimeout(() => {
+                state.debounceTimers.delete(filePath);
+                handleFileChange(pi, filePath, state);
+            }, DEBOUNCE_MS);
+            state.debounceTimers.set(filePath, timer);
+        });
+        watcher.on("error", (err) => {
+            console.error(`[pi-vault-mind] Watcher error for vault "${name}":`, err);
+        });
+        state.watchers.set(name, watcher);
+    }
+    console.log(`[pi-vault-mind] Watcher started. Monitoring ${state.watchers.size} vault(s).`);
+}
+export function stopWatcher(state) {
+    state.running = false;
+    // Clear debounce timers
+    for (const [, timer] of state.debounceTimers) {
+        clearTimeout(timer);
+    }
+    state.debounceTimers.clear();
+    // Close all file watchers
+    for (const [name, watcher] of state.watchers) {
+        watcher.close();
+        console.log(`[pi-vault-mind] Stopped watching vault "${name}".`);
+    }
+    state.watchers.clear();
+    state.processing.clear();
+    console.log("[pi-vault-mind] Watcher stopped.");
+}
+function handleFileChange(pi, filePath, state) {
+    if (state.processing.has(filePath))
+        return;
+    const groups = scanFile(filePath);
+    if (groups.length === 0)
+        return;
+    state.processing.add(filePath);
+    console.log(`[pi-vault-mind] Detected ${groups.length} task group(s) in ${filePath}`);
+    // Replace markers with dispatch comments (embeds dispatch ID for writeback)
+    markProcessing(filePath, groups, state.activeDispatches_);
+    // Queue the groups for dispatch
+    for (const group of groups) {
+        state.pendingQueue.push(group);
+    }
+    // Process the queue
+    processQueue(pi, state);
+}
+export function processQueue(pi, state) {
+    while (state.pendingQueue.length > 0 && state.activeDispatches < state.maxConcurrent) {
+        const group = state.pendingQueue.shift();
+        if (!group)
+            break;
+        dispatchGroup(pi, group, state);
+    }
+}
+function dispatchGroup(pi, group, state) {
+    state.activeDispatches++;
+    const role = group.role;
+    const agentMap = {
+        miner: "vault-mind-miner",
+        manager: "vault-mind-manager",
+        broadcaster: "vault-mind-broadcaster",
+        "heavy-lifter": "vault-mind-heavy-lifter",
+        delegator: "vault-mind-heavy-lifter",
+        researcher: "vault-mind-miner",
+        podcast: "vault-mind-broadcaster",
+    };
+    const agentName = agentMap[role] || `vault-mind-${role}`;
+    // Update the dispatch record with the resolved agent name
+    const record = state.activeDispatches_.get(group.dispatchId);
+    if (record)
+        record.agentName = agentName;
+    // Build writeback instructions: tell the subagent exactly how to replace its marker
+    const writebackInstructions = [
+        "## Result Writeback",
+        "After completing your work, replace the dispatch marker in the source file with a summary:",
+        "",
+        `1. Read the file: \`${group.filePath}\``,
+        `2. Find the comment: \`<!-- pi-dispatch:${group.dispatchId} -->\``,
+        "3. Replace it with a brief summary of your findings (1-3 lines), prefixed with `> ` to render as a blockquote",
+        "",
+        "Example replacement:",
+        "> Extracted 3 entities (PPO, Reward Model, RLHF) and 2 relationships. Stored in LanceDB. See [[Agent/Inbox/2026-06-06-rlhf-claims]].",
+        "",
+        "This ensures results are visible directly in the source note.",
+    ].join("\n");
+    // Build the task prompt for the Manager agent
+    const taskDescription = [
+        `The vault watcher detected an @agent-${role} marker in ${group.filePath}.`,
+        `Dispatch ID: ${group.dispatchId}`,
+        "",
+        "Please dispatch a subagent to handle it:",
+        "",
+        "```",
+        "subagent({",
+        `  agent: "${agentName}",`,
+        `  task: ${JSON.stringify(`${group.combinedInstruction}\n\n${writebackInstructions}`)},`,
+        `  context: "fork",`,
+        "  async: true,",
+        "})",
+        "```",
+        "",
+        `Role: ${agentName}`,
+        `Source file: ${group.filePath}`,
+        `Dispatch ID: ${group.dispatchId}`,
+        `Group: ${role}${group.taskId ? ` (id: ${group.taskId})` : ""} (${group.markers.length} marker(s))`,
+    ].join("\n");
+    // Send as a user message to trigger an agent turn
+    try {
+        pi.sendUserMessage(taskDescription, { deliverAs: "followUp" });
+        console.log(`[pi-vault-mind] Dispatched ${agentName} task for ${group.filePath}`);
+    }
+    catch (err) {
+        console.error(`[pi-vault-mind] Failed to dispatch ${agentName}:`, err.message);
+    }
+    finally {
+        state.activeDispatches--;
+        // Check for more work
+        processQueue(pi, state);
+    }
+}
+export function getWatcherStatus(state) {
+    const lines = [
+        `Watcher: ${state.running ? "RUNNING" : "STOPPED"}`,
+        `Active vaults: ${state.watchers.size}`,
+        `Active dispatches: ${state.activeDispatches}`,
+        `Pending queue: ${state.pendingQueue.length}`,
+        `Max concurrent: ${state.maxConcurrent}`,
+        `Dispatch records: ${state.activeDispatches_.size}`,
+    ];
+    if (state.watchers.size > 0) {
+        lines.push("");
+        lines.push("Watched vaults:");
+        for (const [name] of state.watchers) {
+            lines.push(`  - ${name}`);
+        }
+    }
+    if (state.activeDispatches_.size > 0) {
+        lines.push("");
+        lines.push("Recent dispatches:");
+        const recent = [...state.activeDispatches_.values()].slice(-10);
+        for (const d of recent) {
+            const relPath = d.filePath.split("/").slice(-3).join("/");
+            lines.push(`  ${d.dispatchId} → ${d.agentName} (${relPath}, ${d.markerCount} markers)`);
+        }
+    }
+    return lines.join("\n");
+}
+export function createWatcherState() {
+    return {
+        watchers: new Map(),
+        debounceTimers: new Map(),
+        processing: new Set(),
+        running: false,
+        maxConcurrent: MAX_CONCURRENT,
+        activeDispatches: 0,
+        pendingQueue: [],
+        activeDispatches_: new Map(),
+    };
+}

package/dist/src/widget.d.ts

@@ -0,0 +1,3 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+export declare const WIDGET_KEY = "pi-vault-mind-active";
+export declare const updateActiveCollectionWidget: (ctx: ExtensionContext) => void;

package/dist/src/widget.js

@@ -0,0 +1,12 @@
+import { getActiveCollection } from "./state.js";
+export const WIDGET_KEY = "pi-vault-mind-active";
+export const updateActiveCollectionWidget = (ctx) => {
+    const active = getActiveCollection(ctx.cwd);
+    // We use a component-based widget to style it nicely above the editor
+    // If ctx.ui.setWidget doesn't support the callback in older versions,
+    // it will just fall back, but we pass strings.
+    // However, the doc says string arrays are supported for RPC and function callbacks for TUI.
+    // The doc also says: ctx.ui.setWidget("my-widget", ["Line 1", "Line 2"], { placement: "aboveEditor" });
+    const lines = [`[Active Collection: ${active}]`];
+    ctx.ui.setWidget(WIDGET_KEY, lines, { placement: "aboveEditor" });
+};

package/dist/test/index.test.d.ts

@@ -0,0 +1 @@
+export {};