pi-vault-mind 0.8.0 → 0.8.3

package/dist/src/agent-bus/LLMProvider.d.ts

@@ -0,0 +1,36 @@
+export interface LLMConfig {
+    model: string;
+    /** Primary remote endpoint (e.g. Modal deployment). */
+    remoteUrl?: string;
+    /** Local fallback endpoint (e.g. Ollama). */
+    localUrl?: string;
+    /** API key for Bearer auth. Defaults to "ollama" (Ollama ignores it). */
+    apiKey?: string;
+    temperature?: number;
+}
+export interface PromptOptions {
+    systemPrompt?: string;
+    jsonMode?: boolean;
+}
+/**
+ * LLMProvider
+ *
+ * Interface for talking to the intelligence layer.
+ * A concrete implementation would hit an Ollama endpoint or external API.
+ */
+export declare abstract class LLMProvider {
+    protected config: LLMConfig;
+    constructor(config: LLMConfig);
+    abstract prompt(text: string, options?: PromptOptions): Promise<string>;
+}
+/**
+ * AgentModelProvider — real LLM access for internal agents.
+ * Remote-first, local-fallback: tries remoteUrl, then falls back
+ * to localUrl (typically a local Ollama instance) on any failure.
+ * Both endpoints speak OpenAI-compatible `/v1/chat/completions`.
+ *
+ * Pattern adapted from kylebrodeur/microfactory PiModelRouterLLMProvider (MIT).
+ */
+export declare class AgentModelProvider extends LLMProvider {
+    prompt(text: string, options?: PromptOptions): Promise<string>;
+}

package/dist/src/agent-bus/LLMProvider.js

@@ -0,0 +1,125 @@
+/**
+ * LLMProvider
+ *
+ * Interface for talking to the intelligence layer.
+ * A concrete implementation would hit an Ollama endpoint or external API.
+ */
+export class LLMProvider {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+}
+/**
+ * AgentModelProvider — real LLM access for internal agents.
+ * Remote-first, local-fallback: tries remoteUrl, then falls back
+ * to localUrl (typically a local Ollama instance) on any failure.
+ * Both endpoints speak OpenAI-compatible `/v1/chat/completions`.
+ *
+ * Pattern adapted from kylebrodeur/microfactory PiModelRouterLLMProvider (MIT).
+ */
+export class AgentModelProvider extends LLMProvider {
+    async prompt(text, options) {
+        const jsonMode = options?.jsonMode === true;
+        const messages = [];
+        if (options?.systemPrompt) {
+            messages.push({ role: "system", content: options.systemPrompt });
+        }
+        messages.push({ role: "user", content: text });
+        const body = JSON.stringify({
+            model: this.config.model,
+            messages,
+            temperature: this.config.temperature ?? 0.1,
+            stream: false,
+        });
+        const endpoints = [this.config.remoteUrl ?? "http://127.0.0.1:11434/v1"];
+        if (this.config.localUrl) {
+            endpoints.push(this.config.localUrl);
+        }
+        let lastError = null;
+        for (const baseUrl of endpoints) {
+            try {
+                const resp = await fetch(`${baseUrl}/chat/completions`, {
+                    method: "POST",
+                    headers: {
+                        "Content-Type": "application/json",
+                        Authorization: `Bearer ${this.config.apiKey ?? "ollama"}`,
+                    },
+                    body,
+                });
+                if (!resp.ok) {
+                    const errBody = await resp.text().catch(() => "");
+                    throw new Error(`HTTP ${resp.status}: ${errBody.slice(0, 200)}`);
+                }
+                const data = (await resp.json());
+                let result = (data.choices?.[0]?.message?.content ?? "").trim();
+                if (!result)
+                    throw new Error("Model returned empty response");
+                if (jsonMode)
+                    result = extractJSON(result);
+                return result;
+            }
+            catch (err) {
+                lastError = err instanceof Error ? err : new Error(String(err));
+                console.warn(`[AgentModelProvider] ${baseUrl} failed: ${lastError.message} — trying next`);
+            }
+        }
+        throw lastError ?? new Error("AgentModelProvider: no endpoints configured");
+    }
+}
+/**
+ * Strip markdown fences and extract the first valid JSON object/array.
+ * Local models (Gemma, Llama, etc.) often wrap JSON in ```json fences
+ * even when explicitly told not to.
+ */
+function extractJSON(raw) {
+    // Try direct parse first — most common case
+    try {
+        JSON.parse(raw);
+        return raw;
+    }
+    catch {
+        // fall through to fence stripping
+    }
+    // Strip ```json / ``` fences
+    const stripped = raw
+        .replace(/^```(?:json)?\s*\n?/gm, "")
+        .replace(/\n?```\s*$/gm, "")
+        .trim();
+    // Find first { or [ and try to parse from there
+    const start = Math.min(...[stripped.indexOf("{"), stripped.indexOf("[")].filter((i) => i >= 0));
+    if (start >= 0) {
+        const candidate = stripped.slice(start);
+        try {
+            JSON.parse(candidate);
+            return candidate;
+        }
+        catch {
+            // last resort: find balanced braces
+            let depth = 0;
+            let end = start;
+            const target = candidate[0] === "{" ? "}" : "]";
+            const open = candidate[0];
+            for (let i = 0; i < candidate.length; i++) {
+                if (candidate[i] === open)
+                    depth++;
+                else if (candidate[i] === target) {
+                    depth--;
+                    if (depth === 0) {
+                        end = i + 1;
+                        break;
+                    }
+                }
+            }
+            const balanced = candidate.slice(0, end);
+            try {
+                JSON.parse(balanced);
+                return balanced;
+            }
+            catch {
+                // give up, return stripped
+            }
+        }
+    }
+    return stripped;
+}

package/dist/src/agent-bus/MessageBus.d.ts

@@ -0,0 +1,47 @@
+export interface Message {
+    id: string;
+    topic: string;
+    payload: Record<string, unknown>;
+    senderId: string;
+    timestamp: number;
+}
+export type MessageHandler = (message: Message) => void | Promise<void>;
+/**
+ * MessageBus
+ *
+ * An event-driven stigmergic environment for agents to drop messages (pheromones).
+ * Instead of explicitly addressing one another, agents broadcast onto topics,
+ * simulating environment-mediated coordination (Stigmergy) dropping O(n²) scaling.
+ */
+export declare class MessageBus {
+    private listeners;
+    private history;
+    private maxHistorySize;
+    constructor(maxHistorySize?: number);
+    /**
+     * Subscribe to a topic
+     */
+    subscribe(topic: string, handler: MessageHandler): void;
+    /**
+     * Unsubscribe from a topic
+     */
+    unsubscribe(topic: string, handler: MessageHandler): void;
+    /**
+     * Broadcast a message to a topic
+     */
+    publish(topic: string, senderId: string, payload: Record<string, unknown>): Promise<void>;
+    /**
+     * Get max history size
+     */
+    getHistoryLimit(): number;
+    /**
+     * Set max history size (0 = unlimited)
+     */
+    setHistoryLimit(limit: number): void;
+    /** Trim history if over limit */
+    private _trimHistory;
+    /**
+     * Get all messages for a given topic
+     */
+    getHistory(topic?: string): Message[];
+}

package/dist/src/agent-bus/MessageBus.js

@@ -0,0 +1,81 @@
+import { randomUUID } from "node:crypto";
+/**
+ * MessageBus
+ *
+ * An event-driven stigmergic environment for agents to drop messages (pheromones).
+ * Instead of explicitly addressing one another, agents broadcast onto topics,
+ * simulating environment-mediated coordination (Stigmergy) dropping O(n²) scaling.
+ */
+export class MessageBus {
+    listeners = new Map();
+    history = [];
+    maxHistorySize;
+    constructor(maxHistorySize = 10000) {
+        this.maxHistorySize = Math.max(0, maxHistorySize);
+    }
+    /**
+     * Subscribe to a topic
+     */
+    subscribe(topic, handler) {
+        if (!this.listeners.has(topic)) {
+            this.listeners.set(topic, new Set());
+        }
+        this.listeners.get(topic)?.add(handler);
+    }
+    /**
+     * Unsubscribe from a topic
+     */
+    unsubscribe(topic, handler) {
+        const topicListeners = this.listeners.get(topic);
+        if (topicListeners) {
+            topicListeners.delete(handler);
+        }
+    }
+    /**
+     * Broadcast a message to a topic
+     */
+    async publish(topic, senderId, payload) {
+        const message = {
+            id: randomUUID(),
+            topic,
+            payload,
+            senderId,
+            timestamp: Date.now(),
+        };
+        this.history.push(message);
+        this._trimHistory();
+        const topicListeners = this.listeners.get(topic);
+        if (topicListeners) {
+            const promises = Array.from(topicListeners).map((handler) => handler(message));
+            await Promise.allSettled(promises);
+        }
+    }
+    /**
+     * Get max history size
+     */
+    getHistoryLimit() {
+        return this.maxHistorySize;
+    }
+    /**
+     * Set max history size (0 = unlimited)
+     */
+    setHistoryLimit(limit) {
+        this.maxHistorySize = Math.max(0, limit);
+        this._trimHistory();
+    }
+    /** Trim history if over limit */
+    _trimHistory() {
+        if (this.maxHistorySize > 0 && this.history.length > this.maxHistorySize) {
+            this.history = this.history.slice(-this.maxHistorySize);
+        }
+    }
+    /**
+     * Get all messages for a given topic
+     */
+    getHistory(topic) {
+        if (topic) {
+            return this.history.filter((m) => m.topic === topic);
+        }
+        return [...this.history];
+    }
+}

package/dist/src/agent-bus/TaskQueue.d.ts

@@ -0,0 +1,27 @@
+export interface Task<TInput = unknown, TOutput = unknown> {
+    id: string;
+    type: string;
+    input: TInput;
+    status: "pending" | "in_progress" | "completed" | "failed";
+    result?: TOutput;
+    error?: string;
+    assignedTo?: string;
+    createdAt: number;
+    updatedAt: number;
+}
+/**
+ * TaskQueue
+ *
+ * Simple abstraction for managing asynchronous units of work.
+ * Could represent a coding file to parse, or a physical 3D print job.
+ */
+export declare class TaskQueue {
+    private tasks;
+    add<TInput>(type: string, input: TInput): string;
+    get(id: string): Task | undefined;
+    getAll(): Task[];
+    getPending(): Task[];
+    claim(id: string, agentId: string): boolean;
+    complete<TOutput>(id: string, agentId: string, result: TOutput): void;
+    fail(id: string, agentId: string, error: string): void;
+}

package/dist/src/agent-bus/TaskQueue.js

@@ -0,0 +1,57 @@
+import { randomUUID } from "node:crypto";
+/**
+ * TaskQueue
+ *
+ * Simple abstraction for managing asynchronous units of work.
+ * Could represent a coding file to parse, or a physical 3D print job.
+ */
+export class TaskQueue {
+    tasks = new Map();
+    add(type, input) {
+        const id = randomUUID();
+        this.tasks.set(id, {
+            id,
+            type,
+            input,
+            status: "pending",
+            createdAt: Date.now(),
+            updatedAt: Date.now(),
+        });
+        return id;
+    }
+    get(id) {
+        return this.tasks.get(id);
+    }
+    getAll() {
+        return Array.from(this.tasks.values());
+    }
+    getPending() {
+        return Array.from(this.tasks.values()).filter((t) => t.status === "pending");
+    }
+    claim(id, agentId) {
+        const task = this.tasks.get(id);
+        if (task && task.status === "pending") {
+            task.status = "in_progress";
+            task.assignedTo = agentId;
+            task.updatedAt = Date.now();
+            return true;
+        }
+        return false;
+    }
+    complete(id, agentId, result) {
+        const task = this.tasks.get(id);
+        if (task && task.assignedTo === agentId) {
+            task.status = "completed";
+            task.result = result;
+            task.updatedAt = Date.now();
+        }
+    }
+    fail(id, agentId, error) {
+        const task = this.tasks.get(id);
+        if (task && task.assignedTo === agentId) {
+            task.status = "failed";
+            task.error = error;
+            task.updatedAt = Date.now();
+        }
+    }
+}

package/dist/src/agent-bus/index.d.ts

@@ -0,0 +1,6 @@
+export { Agent, type AgentConfig } from "./Agent.js";
+export { AgentLoader, type AgentFileDefinition, type AgentLoaderConfig } from "./AgentLoader.js";
+export { AgentRegistry, type AgentConstructor } from "./AgentRegistry.js";
+export { LLMProvider, AgentModelProvider, type LLMConfig, type PromptOptions, } from "./LLMProvider.js";
+export { MessageBus, type Message, type MessageHandler } from "./MessageBus.js";
+export { TaskQueue, type Task } from "./TaskQueue.js";

package/dist/src/agent-bus/index.js

@@ -0,0 +1,6 @@
+export { Agent } from "./Agent.js";
+export { AgentLoader } from "./AgentLoader.js";
+export { AgentRegistry } from "./AgentRegistry.js";
+export { LLMProvider, AgentModelProvider, } from "./LLMProvider.js";
+export { MessageBus } from "./MessageBus.js";
+export { TaskQueue } from "./TaskQueue.js";

package/dist/src/agents/BroadcasterAgent.d.ts

@@ -0,0 +1,19 @@
+/**
+ * BroadcasterAgent — content distribution agent.
+ *
+ * Allowed tools: read, write, edit, vm_search, vm_fts_search
+ * Cannot write to durable store or publish.
+ * Writes output only under Agent/Presentations/.
+ */
+import { Agent, type AgentConfig } from "../agent-bus/Agent.js";
+import type { LLMProvider } from "../agent-bus/LLMProvider.js";
+import type { MessageBus } from "../agent-bus/MessageBus.js";
+import type { TaskQueue } from "../agent-bus/TaskQueue.js";
+export declare class BroadcasterAgent extends Agent {
+    private taskQueue;
+    constructor(config: AgentConfig, bus: MessageBus, llm?: LLMProvider);
+    setTaskQueue(taskQueue: TaskQueue): void;
+    private onJobAvailable;
+    private executeJob;
+    tick(): Promise<void>;
+}

package/dist/src/agents/BroadcasterAgent.js

@@ -0,0 +1,70 @@
+/**
+ * BroadcasterAgent — content distribution agent.
+ *
+ * Allowed tools: read, write, edit, vm_search, vm_fts_search
+ * Cannot write to durable store or publish.
+ * Writes output only under Agent/Presentations/.
+ */
+import { Agent } from "../agent-bus/Agent.js";
+export class BroadcasterAgent extends Agent {
+    taskQueue = null;
+    constructor(config, bus, llm) {
+        super(config, bus, llm);
+        this.bus.subscribe("JOB_AVAILABLE", this.onJobAvailable.bind(this));
+    }
+    setTaskQueue(taskQueue) {
+        this.taskQueue = taskQueue;
+    }
+    async onJobAvailable(message) {
+        if (!this.taskQueue)
+            return;
+        const job = message.payload;
+        if (job.role !== "broadcaster")
+            return;
+        const taskId = this.taskQueue.add("agent-dispatch", job);
+        if (!this.taskQueue.claim(taskId, this.config.id))
+            return;
+        try {
+            await this.executeJob(job);
+            this.taskQueue.complete(taskId, this.config.id, { dispatchId: job.dispatchId });
+            await this.broadcast("JOB_COMPLETED", {
+                dispatchId: job.dispatchId,
+                agentId: this.config.id,
+                status: "done",
+            });
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            this.taskQueue.fail(taskId, this.config.id, msg);
+            await this.broadcast("JOB_COMPLETED", {
+                dispatchId: job.dispatchId,
+                agentId: this.config.id,
+                status: "failed",
+                error: msg,
+            });
+        }
+    }
+    async executeJob(job) {
+        await this.invokePiTool("read", { path: job.filePath });
+        if (this.llm) {
+            const plan = await this.askLLM(`You are the Broadcaster agent. Task: ${job.instruction}\n\nSource file: ${job.filePath}\n\nCreate content under Agent/Presentations/. You cannot write to the durable store. Plan the tool calls needed. Return JSON: { "tools": [{"name": "...", "args": {...}}] }`);
+            if (plan?.tools) {
+                for (const tool of plan.tools) {
+                    await this.invokePiTool(tool.name, tool.args);
+                }
+            }
+        }
+        await this.invokePiTool("edit", {
+            path: job.filePath,
+            edits: [
+                {
+                    oldText: `<!-- pi-dispatch:${job.dispatchId} -->`,
+                    newText: `> Broadcaster completed. See dispatch ${job.dispatchId}.`,
+                },
+            ],
+        });
+    }
+    async tick() {
+        // Event-driven — work arrives via JOB_AVAILABLE subscription
+    }
+}

package/dist/src/agents/HeavyLifterAgent.d.ts

@@ -0,0 +1,26 @@
+/**
+ * HeavyLifterAgent — external CLI execution agent.
+ *
+ * Allowed tools: read, write, edit, grep, find, ls, bash, vm_search, vm_fts_search
+ * Cannot write to durable store or publish.
+ * Runs bash in isolated worktree.
+ */
+import { Agent, type AgentConfig } from "../agent-bus/Agent.js";
+import type { LLMProvider } from "../agent-bus/LLMProvider.js";
+import type { MessageBus } from "../agent-bus/MessageBus.js";
+import type { TaskQueue } from "../agent-bus/TaskQueue.js";
+export interface DispatchJob {
+    dispatchId: string;
+    role: string;
+    filePath: string;
+    instruction: string;
+    vaultPath: string;
+}
+export declare class HeavyLifterAgent extends Agent {
+    private taskQueue;
+    constructor(config: AgentConfig, bus: MessageBus, llm?: LLMProvider);
+    setTaskQueue(taskQueue: TaskQueue): void;
+    private onJobAvailable;
+    private executeJob;
+    tick(): Promise<void>;
+}

package/dist/src/agents/HeavyLifterAgent.js

@@ -0,0 +1,73 @@
+/**
+ * HeavyLifterAgent — external CLI execution agent.
+ *
+ * Allowed tools: read, write, edit, grep, find, ls, bash, vm_search, vm_fts_search
+ * Cannot write to durable store or publish.
+ * Runs bash in isolated worktree.
+ */
+import { Agent } from "../agent-bus/Agent.js";
+export class HeavyLifterAgent extends Agent {
+    taskQueue = null;
+    constructor(config, bus, llm) {
+        super(config, bus, llm);
+        this.bus.subscribe("JOB_AVAILABLE", this.onJobAvailable.bind(this));
+    }
+    setTaskQueue(taskQueue) {
+        this.taskQueue = taskQueue;
+    }
+    async onJobAvailable(message) {
+        if (!this.taskQueue)
+            return;
+        const job = message.payload;
+        if (job.role !== "heavy-lifter")
+            return;
+        const taskId = this.taskQueue.add("agent-dispatch", job);
+        if (!this.taskQueue.claim(taskId, this.config.id))
+            return;
+        try {
+            await this.executeJob(job);
+            this.taskQueue.complete(taskId, this.config.id, { dispatchId: job.dispatchId });
+            await this.broadcast("JOB_COMPLETED", {
+                dispatchId: job.dispatchId,
+                agentId: this.config.id,
+                status: "done",
+            });
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            this.taskQueue.fail(taskId, this.config.id, msg);
+            await this.broadcast("JOB_COMPLETED", {
+                dispatchId: job.dispatchId,
+                agentId: this.config.id,
+                status: "failed",
+                error: msg,
+            });
+        }
+    }
+    async executeJob(job) {
+        // Read the source file
+        await this.invokePiTool("read", { path: job.filePath });
+        // Execute the instruction — the agent uses its LLM to decide which tools to call
+        if (this.llm) {
+            const plan = await this.askLLM(`You are the Heavy-Lifter agent. Task: ${job.instruction}\n\nSource file: ${job.filePath}\nVault: ${job.vaultPath}\n\nPlan the tool calls needed. Return JSON: { "tools": [{"name": "...", "args": {...}}] }`);
+            if (plan?.tools) {
+                for (const tool of plan.tools) {
+                    await this.invokePiTool(tool.name, tool.args);
+                }
+            }
+        }
+        // Write results back to the source file (replace dispatch marker)
+        await this.invokePiTool("edit", {
+            path: job.filePath,
+            edits: [
+                {
+                    oldText: `<!-- pi-dispatch:${job.dispatchId} -->`,
+                    newText: `> Heavy-Lifter completed. See dispatch ${job.dispatchId}.`,
+                },
+            ],
+        });
+    }
+    async tick() {
+        // HeavyLifter is event-driven — work arrives via JOB_AVAILABLE subscription
+    }
+}

package/dist/src/agents/ManagerAgent.d.ts

@@ -0,0 +1,20 @@
+/**
+ * ManagerAgent — final gate and publishing agent.
+ *
+ * Allowed tools: all vm_* tools + read, write, edit, grep, find, ls, subagent
+ * Write collections: all
+ * Can publish (vm_sync enabled).
+ * Only the Manager can dispatch subagents and publish to the human-facing vault.
+ */
+import { Agent, type AgentConfig } from "../agent-bus/Agent.js";
+import type { LLMProvider } from "../agent-bus/LLMProvider.js";
+import type { MessageBus } from "../agent-bus/MessageBus.js";
+import type { TaskQueue } from "../agent-bus/TaskQueue.js";
+export declare class ManagerAgent extends Agent {
+    private taskQueue;
+    constructor(config: AgentConfig, bus: MessageBus, llm?: LLMProvider);
+    setTaskQueue(taskQueue: TaskQueue): void;
+    private onJobAvailable;
+    private executeJob;
+    tick(): Promise<void>;
+}

package/dist/src/agents/ManagerAgent.js

@@ -0,0 +1,71 @@
+/**
+ * ManagerAgent — final gate and publishing agent.
+ *
+ * Allowed tools: all vm_* tools + read, write, edit, grep, find, ls, subagent
+ * Write collections: all
+ * Can publish (vm_sync enabled).
+ * Only the Manager can dispatch subagents and publish to the human-facing vault.
+ */
+import { Agent } from "../agent-bus/Agent.js";
+export class ManagerAgent extends Agent {
+    taskQueue = null;
+    constructor(config, bus, llm) {
+        super(config, bus, llm);
+        this.bus.subscribe("JOB_AVAILABLE", this.onJobAvailable.bind(this));
+    }
+    setTaskQueue(taskQueue) {
+        this.taskQueue = taskQueue;
+    }
+    async onJobAvailable(message) {
+        if (!this.taskQueue)
+            return;
+        const job = message.payload;
+        if (job.role !== "manager")
+            return;
+        const taskId = this.taskQueue.add("agent-dispatch", job);
+        if (!this.taskQueue.claim(taskId, this.config.id))
+            return;
+        try {
+            await this.executeJob(job);
+            this.taskQueue.complete(taskId, this.config.id, { dispatchId: job.dispatchId });
+            await this.broadcast("JOB_COMPLETED", {
+                dispatchId: job.dispatchId,
+                agentId: this.config.id,
+                status: "done",
+            });
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            this.taskQueue.fail(taskId, this.config.id, msg);
+            await this.broadcast("JOB_COMPLETED", {
+                dispatchId: job.dispatchId,
+                agentId: this.config.id,
+                status: "failed",
+                error: msg,
+            });
+        }
+    }
+    async executeJob(job) {
+        await this.invokePiTool("read", { path: job.filePath });
+        if (this.llm) {
+            const plan = await this.askLLM(`You are the Manager agent. Task: ${job.instruction}\n\nSource file: ${job.filePath}\n\nYou are the final gate. You may dispatch subagents, write to any collection, and publish to the vault. Plan the tool calls needed. Return JSON: { "tools": [{"name": "...", "args": {...}}] }`);
+            if (plan?.tools) {
+                for (const tool of plan.tools) {
+                    await this.invokePiTool(tool.name, tool.args);
+                }
+            }
+        }
+        await this.invokePiTool("edit", {
+            path: job.filePath,
+            edits: [
+                {
+                    oldText: `<!-- pi-dispatch:${job.dispatchId} -->`,
+                    newText: `> Manager completed. See dispatch ${job.dispatchId}.`,
+                },
+            ],
+        });
+    }
+    async tick() {
+        // Event-driven — work arrives via JOB_AVAILABLE subscription
+    }
+}