pi-vault-mind 0.8.0 → 0.8.3

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 0.8.0 - 2026-06-24
+
+### Added
+
+- `discover_schema` tool and `/vm discover-schema` command — infer schema from a `.jsonl` file and register it as a collection.
+- `tombstone_entry` tool and `/vm tombstone` command — redact a JSONL entry in place while preserving the append-only log format.
+- `/vm query` command — hybrid semantic + FTS search over a collection from the slash command tree.
+- `/vm collection list` command — list configured collections without opening the TUI selector.
+- `ask_intake` interactive questionnaire tool with optional persistence to the ledger, vault, or both.
+- Advanced deduping options (`dedupMode`, `dedupThreshold`) and background auto-indexing hooks for collection directories.
+- Always-on capture **Tier A** recipe in `docs/getting-started/CAPTURE_SETUP.md` (iOS Shortcut + Actions for Obsidian, voice memo → Shortcut, desktop Templater hotkey).
+- Vault-specific pi config + TUI launcher in the Obsidian plugin: reads `<vault>/.pi/agent/system.md` and launches pi from setup/status views.
+- Published `pi-vault-mind@0.8.0` and `obsidian-pi-vault-mind@0.1.0` to npm.
+
+### Fixed
+
+- HOME capture path bug: `expandHome()` now falls back to `process.env.USERPROFILE` on Windows and handles bare `~` correctly.
+- Broken internal markdown links after the 0.7.6 docs reorganization.
+- Removed stale `site/` MkDocs build output from git tracking.
+
 ## 0.7.1 - 2026-06-14
 
 ### Fixed

package/README.md

@@ -10,17 +10,17 @@ Passive Obsidian vault extension for the [pi](https://github.com/mariozechner/pi
 
 > Looking for the legacy ledger-first extension (predecessor project)?
 > See [kylebrodeur/pi-qmd-ledger](https://github.com/kylebrodeur/pi-qmd-ledger).
-> This project was renamed twice: `pi-qmd-ledger` → `pi-llm-wiki` (intermediate) → `pi-vault-mind` (current).
+> This project was renamed twice: `pi-qmd-ledger` → `pi-knowledge-store` (intermediate) → `pi-vault-mind` (current).
 
 ## Features
 
 - **Passive File Watcher** — drop `@agent-Miner`, `@agent-Broadcaster`, etc. in any Obsidian note. Save the file. The watcher detects the marker, groups by role, and dispatches isolated subagent forks (`vault-mind-{role}` agents). No chat pollution, no manual triggers.
 - **Multi-Agent Architecture** — five specialist agents under the `vault-mind-{role}` skill naming: **Manager** (interactive orchestrator), **Miner** (research + entity extraction), **Broadcaster** (NotebookLM artifacts), **Heavy-Lifter** (external delegation), **Watcher** (passive file observer).
 - **LanceDB Vector + FTS + Graph** — hybrid semantic + keyword search with automatic entity extraction and BFS graph traversal. All local, no external binaries.
-- **JSONL Source-of-Truth + LanceDB Index** — every fact lives in a durable, human-readable, version-control-friendly `collections/*.jsonl` file. The LanceDB index is derived and rebuildable via `/wiki reindex --all --reembed`.
+- **JSONL Source-of-Truth + LanceDB Index** — every fact lives in a durable, human-readable, version-control-friendly `collections/*.jsonl` file. The LanceDB index is derived and rebuildable via `/vm reindex --all --reembed`.
 - **Bidirectional Obsidian Sync** — substantial entries (`>200 chars` or tagged `decision`/`insight`/`requirement`) auto-write to `Vault/Agent/Inbox/`. Graph entities render as Obsidian Canvas files.
 - **Two-Layer Config** — global (`~/.pi/agent/vault-mind.config.json`) for shared settings, project (`./pi-vault-mind.config.json`) for project-specific knowledge. Works across all projects from any directory.
-- **Interactive Setup Wizard** — `/wiki setup` walks through vault path, embedding provider, and model selection. CLI mode: `--vault`, `--provider`, `--model` flags for scripting.
+- **Interactive Setup Wizard** — `/vm setup` walks through vault path, embedding provider, and model selection. CLI mode: `--vault`, `--provider`, `--model` flags for scripting.
 
 ## Architecture
 
@@ -70,7 +70,7 @@ See [`docs/architecture/index.md`](docs/architecture/index.md) for the full agen
 pi-vault-mind works on any directory, but for the **full Obsidian experience**, you need a few things in Obsidian itself:
 
 ### Required: An Obsidian vault
-Just point `/wiki setup` at any directory used as an Obsidian vault. pi-vault-mind auto-detects `.obsidian/` and respects `.obsidian/`, `.git/`, `.trash/`.
+Just point `/vm setup` at any directory used as an Obsidian vault. pi-vault-mind auto-detects `.obsidian/` and respects `.obsidian/`, `.git/`, `.trash/`.
 
 ### Recommended: Official Obsidian CLI (1.12+)
 
@@ -165,7 +165,7 @@ These skills let the **Miner, Broadcaster, and Heavy-Lifter agents** produce val
 | **Callouts** | `> [!info]`, `> [!warning]` for syntheses and contradictions |
 | **Embeds** | `![[Note]]` to transclude summaries into synthesis docs |
 | **Obsidian Bases (`.base`)** | Agent-generated dynamic tables/boards/kanbans in `Agent/Tasks/` |
-| **JSON Canvas (`.canvas`)** | `wiki_sync(format="canvas")` writes entity graph as Canvas JSON |
+| **JSON Canvas (`.canvas`)** | `vm_sync(format="canvas")` writes entity graph as Canvas JSON |
 | **Obsidian Sync** | Primary sync mechanism across devices |
 
 ### Optional: NotebookLM integration (Broadcaster)
@@ -209,7 +209,7 @@ pi install git:git@github.com:kylebrodeur/pi-vault-mind
 ### 2. Configure (interactive wizard)
 
 ```
-/wiki setup
+/vm setup
 ```
 
 This walks you through: vault path → embedding provider → Ollama model (if applicable).
@@ -217,20 +217,20 @@ This walks you through: vault path → embedding provider → Ollama model (if a
 Or via CLI for scripting:
 
 ```bash
-/wiki setup --vault /home/you/Obsidian/MyVault --provider transformers
-/wiki setup --vault /home/you/Obsidian/MyVault --provider ollama --model embeddinggemma
+/vm setup --vault /home/you/Obsidian/MyVault --provider transformers
+/vm setup --vault /home/you/Obsidian/MyVault --provider ollama --model embeddinggemma
 ```
 
 Config is written to `~/.pi/agent/vault-mind.config.json` — it applies globally
 no matter which project directory you open pi from.
 
-You can re-run `/wiki setup` anytime to view or change settings.
+You can re-run `/vm setup` anytime to view or change settings.
 
 ### 3. Start using
 
 ```
-append_wiki(collection="main", mode="autopilot", entry={"id":"1","domain":"auth","fact":"JWT tokens expire after 1 hour","tag":"security"})
-wiki_search(collection="main", query="token expiry")
+vm_append(collection="main", mode="autopilot", entry={"id":"1","domain":"auth","fact":"JWT tokens expire after 1 hour","tag":"security"})
+vm_search(collection="main", query="token expiry")
 ```
 
 Entries are automatically embedded and stored in LanceDB. If graph is enabled, entities and relations are also extracted.
@@ -257,7 +257,7 @@ Edit `pi-vault-mind.config.json` to match your domain:
       "filterField": "tag"
     }
   ],
-  "wiki": {
+  "vaultMind": {
     "dataDir": ".lancedb",
     "embedding": {
       "provider": "transformers",
@@ -329,38 +329,38 @@ Edit `pi-vault-mind.config.json` to match your domain:
 
 | Tool               | Purpose                                                 |
 | ------------------ | ------------------------------------------------------- |
-| `wiki_search`       | Semantic search via LanceDB (vector + FTS)       |
-| `wiki_fts_search`    | Exact keyword full-text search (Tantivy BM25)      |
-| `wiki_graph_query`  | Traverse entity connections in the graph layer          |
-| `wiki_status`       | Show LanceDB table sizes and health                     |
-| `query_wiki`      | Deterministic JSONL search by collection name           |
-| `append_wiki`     | Append with strict/gated/autopilot modes + dual-write   |
-| `configure_wiki`  | Read or update config at runtime                        |
-| `describe_wiki`   | Introspect schema, count, and sample entries            |
-| `wiki_stats`      | Dashboard: counts, sizes, LanceDB status                |
-| `wiki_export`     | Export to JSON, CSV, or Markdown                        |
-| `promote_wiki`    | Promote entries between collections via pending queue  |
+| `vm_search`       | Semantic search via LanceDB (vector + FTS)       |
+| `vm_fts_search`    | Exact keyword full-text search (Tantivy BM25)      |
+| `vm_graph_query`  | Traverse entity connections in the graph layer          |
+| `vm_status`       | Show LanceDB table sizes and health                     |
+| `vm_query`      | Deterministic JSONL search by collection name           |
+| `vm_append`     | Append with strict/gated/autopilot modes + dual-write   |
+| `vm_configure`  | Read or update config at runtime                        |
+| `vm_describe`   | Introspect schema, count, and sample entries            |
+| `vm_stats`      | Dashboard: counts, sizes, LanceDB status                |
+| `vm_export`     | Export to JSON, CSV, or Markdown                        |
+| `vm_promote`    | Promote entries between collections via pending queue  |
 
 ## Commands
 
 | Command                        | Purpose                                                  |
 | ------------------------------ | -------------------------------------------------------- |
-| `/wiki help`                   | Show usage help                                          |
-| `/wiki setup`                  | **Interactive global config wizard** (vault, embedding) |
-| `/wiki init`                   | Scaffold project config + collections                    |
-| `/wiki validate`               | Health check LanceDB, config, and all collection paths   |
-| `/wiki approve [collection]`   | Batch-review pending entries                              |
-| `/wiki settings`               | Open interactive settings dashboard                       |
-| `/wiki audit`                  | Audit config for missing defaults                         |
-| `/wiki reindex [--all] [--reembed] [--remote]` | Rebuild FTS + vector indexes; `--remote` offloads to Modal |
-| `/wiki collection select`      | Select active collection (shortcut: ctrl+alt+l)          |
-| `/wiki collection create`      | Interactive wizard to create a new collection              |
-| `/wiki injector create`        | Interactive wizard to create a new injector                |
-| `/wiki context enable \| disable \| status` | Manage pi-context integration              |
-| `/wiki embedding status \| use \| model \| models \| pull` | Manage embedding provider |
-| `/wiki modal status \| config \| sync \| jobs \| migrate` | Manage Modal embedding + vector sync |
-| `/wiki watcher start \| stop \| status` | Manage the passive file watcher                  |
-| `/wiki server status` | Show HTTP server status, port, and uptime |
+| `/vm help`                   | Show usage help                                          |
+| `/vm setup`                  | **Interactive global config wizard** (vault, embedding) |
+| `/vm init`                   | Scaffold project config + collections                    |
+| `/vm validate`               | Health check LanceDB, config, and all collection paths   |
+| `/vm approve [collection]`   | Batch-review pending entries                              |
+| `/vm settings`               | Open interactive settings dashboard                       |
+| `/vm audit`                  | Audit config for missing defaults                         |
+| `/vm reindex [--all] [--reembed] [--remote]` | Rebuild FTS + vector indexes; `--remote` offloads to Modal |
+| `/vm collection select`      | Select active collection (shortcut: ctrl+alt+l)          |
+| `/vm collection create`      | Interactive wizard to create a new collection              |
+| `/vm injector create`        | Interactive wizard to create a new injector                |
+| `/vm context enable \| disable \| status` | Manage pi-context integration              |
+| `/vm embedding status \| use \| model \| models \| pull` | Manage embedding provider |
+| `/vm modal status \| config \| sync \| jobs \| migrate` | Manage Modal embedding + vector sync |
+| `/vm watcher start \| stop \| status` | Manage the passive file watcher                  |
+| `/vm server status` | Show HTTP server status, port, and uptime |
 
 ## Documentation
 
@@ -393,7 +393,7 @@ The local extension now integrates the Modal embedding service as a fully
 configurable embedding provider: on-demand `/embed` for search (with an offline
 fallback that degrades to FTS, never crashes), a sync-down path that pulls
 server-side vectors into the local LanceDB with a monotonic `seq` watermark,
-remote bulk re-index (`/wiki reindex --all --reembed --remote`), and debounced +
+remote bulk re-index (`/vm reindex --all --reembed --remote`), and debounced +
 batched append embedding via the coalescer. Existing non-modal users see no
 behavior change. See [docs/integrations/MODAL_EMBEDDING.md](docs/integrations/MODAL_EMBEDDING.md) for the
 full design.
@@ -411,9 +411,9 @@ full design.
 | Doc | Description |
 |---|---|
 | [skills/vault-mind/SKILL.md](skills/vault-mind/SKILL.md) | The Manager skill — what pi auto-loads about this extension |
-| [docs/CHANGELOG.md](docs/CHANGELOG.md) | Version history (rename from `pi-llm-wiki` to `pi-vault-mind` was v0.7.0) |
-| [docs/reference/tools.md](docs/reference/tools.md) | The 11 `wiki_*` and `query_wiki`/`append_wiki`/etc. tools — parameters, return shapes |
-| [docs/reference/commands.md](docs/reference/commands.md) | Full `/wiki` slash command tree |
+| [docs/CHANGELOG.md](docs/CHANGELOG.md) | Version history (rename from `pi-knowledge-store` to `pi-vault-mind` was v0.7.0) |
+| [docs/reference/tools.md](docs/reference/tools.md) | The 11 `vm_*` and `vm_query`/`vm_append`/etc. tools — parameters, return shapes |
+| [docs/reference/commands.md](docs/reference/commands.md) | Full `/vm` slash command tree |
 | [docs/reference/configuration.md](docs/reference/configuration.md) | The complete `pi-vault-mind.config.json` schema |
 | [docs/reference/skill.md](docs/reference/skill.md) | Manifest of all bundled skills and their trigger phrases |
 
@@ -444,7 +444,7 @@ full design.
 
 | Doc | Description |
 |---|---|
-| [docs/_archive/](docs/_archive/) | Historical docs kept for context (e.g. the `pi-llm-wiki` → `pi-vault-mind` rename audit) |
+| [docs/_archive/](docs/_archive/) | Historical docs kept for context (e.g. the `pi-knowledge-store` → `pi-vault-mind` rename audit) |
 | [docs/_archive/legacy-audit.md](docs/_archive/legacy-audit.md) | The 2026-06-08 legacy-terminology audit (139 findings, 13 blockers) and its resolution log. Resolved 2026-06-09; archived 2026-06-16 (in the repo, not on the docs site) |
 
 ## Contributing

package/agents/broadcaster.agent.md

@@ -0,0 +1,30 @@
+---
+type: BroadcasterAgent
+role: broadcaster
+capabilities: [read, write, edit]
+allowed_tools: [read, write, edit, vm_search, vm_fts_search]
+write_collections: []
+can_publish: false
+llm_provider: ollama
+---
+
+# Broadcaster Agent
+
+Content distribution agent for pi-vault-mind. Creates presentations, summaries,
+and external-facing content from vault knowledge.
+
+## Capability Boundary
+
+- **MAY**: read files, write files, edit files
+- **MAY**: search collections via vm_search, vm_fts_search
+- **MUST NOT**: run bash commands, grep, or find
+- **MUST NOT**: write to the durable knowledge store
+- **MUST NOT**: publish or spawn sub-agents
+- Write output only under Agent/Presentations/
+
+## Tool Calling Convention
+
+When calling pi-vault-mind tools, always include your role:
+```
+vm_search({ query: "...", role: "broadcaster" })
+```

package/agents/heavy-lifter.agent.md

@@ -0,0 +1,30 @@
+---
+type: HeavyLifterAgent
+role: heavy-lifter
+capabilities: [read, write, edit, grep, find, ls, bash]
+allowed_tools: [read, write, edit, grep, find, ls, bash, vm_search, vm_fts_search]
+write_collections: []
+can_publish: false
+llm_provider: ollama
+---
+
+# Heavy-Lifter Agent
+
+External CLI execution agent for pi-vault-mind. Runs bash commands in an isolated
+worktree. Cannot write to the durable knowledge store — all findings must be
+routed to the Miner for storage.
+
+## Capability Boundary
+
+- **MAY**: read files, write files, edit files, run bash commands, search with grep/find/ls
+- **MUST NOT**: write to the durable store (vm_append, vm_sync disabled)
+- **MUST NOT**: spawn sub-agents
+- **MUST NOT**: publish to the human-facing vault
+- All bash commands run in an isolated worktree. Do not modify files outside it.
+
+## Tool Calling Convention
+
+When calling pi-vault-mind tools, always include your role:
+```
+vm_search({ query: "...", role: "heavy-lifter" })
+```

package/agents/manager.agent.md

@@ -0,0 +1,29 @@
+---
+type: ManagerAgent
+role: manager
+capabilities: [read, write, edit, grep, find, ls]
+allowed_tools: [read, write, edit, grep, find, ls, vm_search, vm_fts_search, vm_append, vm_sync, vm_promote, vm_query, vm_configure, vm_describe, vm_stats, vm_export, vm_ingest, vm_status, vm_graph_query]
+write_collections: [main, research, presentations]
+can_publish: true
+llm_provider: ollama
+---
+
+# Manager Agent
+
+Final gate and publishing agent for pi-vault-mind. The only role authorized to
+publish to the human-facing vault and dispatch sub-agents.
+
+## Capability Boundary
+
+- **MAY**: all vm_* tools, read, write, edit, grep, find, ls
+- **MAY**: write to any collection
+- **MAY**: publish to the human-facing vault via vm_sync
+- **MAY**: dispatch sub-agents
+- **MUST NOT**: run bash commands
+
+## Tool Calling Convention
+
+When calling pi-vault-mind tools, always include your role:
+```
+vm_sync({ collection: "main", role: "manager" })
+```

package/agents/miner.agent.md

@@ -0,0 +1,29 @@
+---
+type: MinerAgent
+role: miner
+capabilities: [read, write, edit, grep, find, ls]
+allowed_tools: [read, write, edit, grep, find, ls, vm_search, vm_fts_search, vm_append]
+write_collections: [main, research]
+can_publish: false
+llm_provider: ollama
+---
+
+# Miner Agent
+
+Knowledge extraction and storage agent for pi-vault-mind. Extracts entities and
+relationships from vault content and stores them in the durable knowledge store.
+
+## Capability Boundary
+
+- **MAY**: read files, write files, edit files, search with grep/find/ls
+- **MAY**: append to collections 'main' and 'research' via vm_append
+- **MUST NOT**: run bash commands
+- **MUST NOT**: publish to the human-facing vault (vm_sync disabled)
+- **MUST NOT**: spawn sub-agents
+
+## Tool Calling Convention
+
+When calling pi-vault-mind tools, always include your role:
+```
+vm_append({ collection: "main", entry: {...}, role: "miner" })
+```

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

@@ -0,0 +1,49 @@
+import type { LLMProvider } from "./LLMProvider.js";
+import type { Message, MessageBus } from "./MessageBus.js";
+export interface AgentConfig {
+    id: string;
+    role: string;
+    capabilities: string[];
+}
+/**
+ * Base Agent
+ *
+ * Agnostic agent that sits on the MessageBus.
+ * Can be extended for Coding Tasks or Physical Manufacturing Tasks.
+ */
+export declare abstract class Agent {
+    config: AgentConfig;
+    protected bus: MessageBus;
+    protected llm?: LLMProvider;
+    constructor(config: AgentConfig, bus: MessageBus, llm?: LLMProvider);
+    /**
+     * Broadcast a message to the environment
+     */
+    broadcast(topic: string, payload: Record<string, unknown>): Promise<void>;
+    /**
+     * Direct message another agent
+     */
+    sendDirect(targetAgentId: string, payload: Record<string, unknown>): Promise<void>;
+    /**
+     * Hook for handling incoming messages. To be overridden by implementations.
+     */
+    protected handleMessage(message: Message): Promise<void>;
+    /**
+     * Perform an LLM-driven decision in JSON mode
+     */
+    protected askLLM<T = unknown>(promptText: string, jsonMode?: true): Promise<T | null>;
+    protected askLLM(promptText: string, jsonMode: false): Promise<string>;
+    /**
+     * The main tick or tick-equivalent.
+     * If running in an event loop (e.g. manufacturing), override this.
+     */
+    abstract tick(): Promise<void>;
+    /**
+     * Helper to invoke a Pi tool via the Pi Tool Bridge.
+     * Agent publishes a request and awaits a response on a unique topic.
+     * @param toolName The name of the pi.tool to invoke (e.g., 'append_ledger').
+     * @param args The arguments to pass to the pi.tool.
+     * @param timeoutMs Maximum time to wait for a response from the bridge.
+     */
+    protected invokePiTool(toolName: string, args: Record<string, unknown>, timeoutMs?: number): Promise<unknown>;
+}

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

@@ -0,0 +1,97 @@
+import { randomUUID } from "node:crypto";
+/**
+ * Base Agent
+ *
+ * Agnostic agent that sits on the MessageBus.
+ * Can be extended for Coding Tasks or Physical Manufacturing Tasks.
+ */
+export class Agent {
+    config;
+    bus;
+    llm;
+    constructor(config, bus, llm) {
+        this.config = config;
+        this.bus = bus;
+        this.llm = llm;
+        // Subscribe to direct messages and broadcasts
+        this.bus.subscribe(`direct:${this.config.id}`, this.handleMessage.bind(this));
+        this.bus.subscribe("broadcast", this.handleMessage.bind(this));
+    }
+    /**
+     * Broadcast a message to the environment
+     */
+    async broadcast(topic, payload) {
+        await this.bus.publish(topic, this.config.id, payload);
+    }
+    /**
+     * Direct message another agent
+     */
+    async sendDirect(targetAgentId, payload) {
+        await this.bus.publish(`direct:${targetAgentId}`, this.config.id, payload);
+    }
+    /**
+     * Hook for handling incoming messages. To be overridden by implementations.
+     */
+    async handleMessage(message) {
+        // Default: Do nothing
+    }
+    async askLLM(promptText, jsonMode = true) {
+        if (!this.llm) {
+            throw new Error(`Agent ${this.config.id} has no LLM provider attached.`);
+        }
+        const response = await this.llm.prompt(promptText, { jsonMode });
+        if (jsonMode) {
+            try {
+                return JSON.parse(response);
+            }
+            catch {
+                console.error(`Agent ${this.config.id} failed to parse JSON from LLM:`, response);
+                return null;
+            }
+        }
+        return response;
+    }
+    /**
+     * Helper to invoke a Pi tool via the Pi Tool Bridge.
+     * Agent publishes a request and awaits a response on a unique topic.
+     * @param toolName The name of the pi.tool to invoke (e.g., 'append_ledger').
+     * @param args The arguments to pass to the pi.tool.
+     * @param timeoutMs Maximum time to wait for a response from the bridge.
+     */
+    async invokePiTool(toolName, args, timeoutMs = 30000) {
+        const requestId = randomUUID();
+        const requestTopic = "pi_tool_bridge_requests";
+        const responseTopic = `pi_tool_bridge_responses:${this.config.id}:${requestId}`;
+        return new Promise((resolve, reject) => {
+            // biome-ignore lint/style/useConst: assigned after handler/subscribe setup
+            let timeout;
+            const cleanup = () => {
+                clearTimeout(timeout);
+                this.bus.unsubscribe(responseTopic, handler);
+            };
+            const handler = (message) => {
+                if (message.payload.requestId === requestId) {
+                    cleanup();
+                    if (message.payload.error) {
+                        reject(new Error(String(message.payload.error)));
+                    }
+                    else {
+                        resolve(message.payload.result);
+                    }
+                }
+            };
+            this.bus.subscribe(responseTopic, handler);
+            timeout = setTimeout(() => {
+                cleanup();
+                reject(new Error(`Pi tool invocation timed out for tool: '${toolName}', requestId: ${requestId}`));
+            }, timeoutMs);
+            void this.broadcast(requestTopic, {
+                requestId,
+                agentId: this.config.id,
+                toolName,
+                args,
+                responseTopic,
+            });
+        });
+    }
+}

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

@@ -0,0 +1,33 @@
+import type { Agent } from "./Agent.js";
+import type { LLMProvider } from "./LLMProvider.js";
+import type { MessageBus } from "./MessageBus.js";
+export interface AgentFileDefinition {
+    type: string;
+    role: string;
+    capabilities: string[];
+    llm_provider: string;
+    llm_model: string;
+    allowed_tools?: string[];
+    write_collections?: string[];
+    can_publish?: boolean;
+    config_dir?: string;
+    [key: string]: unknown;
+}
+export interface AgentLoaderConfig {
+    agentsDirectory: string;
+    bus: MessageBus;
+    llmProviderFactory: (providerName: string, model: string) => Promise<LLMProvider | null>;
+}
+/**
+ * AgentLoader reads Markdown files with YAML frontmatter from a directory
+ * and instantiates agents using the AgentRegistry.
+ */
+export declare class AgentLoader {
+    private config;
+    constructor(config: AgentLoaderConfig);
+    /**
+     * Loads all agents defined in the .agents/ directory.
+     */
+    loadAgents(): Promise<Agent[]>;
+    private parseMarkdownWithFrontmatter;
+}

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

@@ -0,0 +1,102 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { AgentRegistry } from "./AgentRegistry.js";
+/**
+ * AgentLoader reads Markdown files with YAML frontmatter from a directory
+ * and instantiates agents using the AgentRegistry.
+ */
+export class AgentLoader {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Loads all agents defined in the .agents/ directory.
+     */
+    async loadAgents() {
+        const { agentsDirectory, bus, llmProviderFactory } = this.config;
+        const agents = [];
+        try {
+            if (!fs.existsSync(agentsDirectory)) {
+                console.warn(`[AgentLoader] Agents directory ${agentsDirectory} not found. Skipping.`);
+                return [];
+            }
+            const files = fs.readdirSync(agentsDirectory);
+            for (const file of files) {
+                if (file.endsWith(".agent.md")) {
+                    const absolutePath = path.join(agentsDirectory, file);
+                    const content = fs.readFileSync(absolutePath, "utf8");
+                    const { frontmatter } = this.parseMarkdownWithFrontmatter(content);
+                    if (!frontmatter || typeof frontmatter.type !== "string") {
+                        console.error(`[AgentLoader] Agent file ${file} is missing 'type' in frontmatter. Skipping.`);
+                        continue;
+                    }
+                    const agentType = frontmatter.type;
+                    const Constructor = AgentRegistry.get(agentType);
+                    if (!Constructor) {
+                        console.error(`[AgentLoader] Agent file ${file} specifies type '${agentType}', but no such agent type is registered. Skipping.`);
+                        continue;
+                    }
+                    const agentConfig = {
+                        id: path.basename(file, ".agent.md"),
+                        role: frontmatter.role || "General Purpose",
+                        capabilities: frontmatter.capabilities || [],
+                    };
+                    // Create LLM Provider if specified
+                    let llm = null;
+                    if (typeof frontmatter.llm_provider === "string" &&
+                        typeof frontmatter.llm_model === "string") {
+                        llm = await llmProviderFactory(frontmatter.llm_provider, frontmatter.llm_model);
+                    }
+                    // Instantiate the agent
+                    const agent = new Constructor(agentConfig, bus, llm ?? undefined);
+                    agents.push(agent);
+                    console.log(`[AgentLoader] Loaded agent: ${agentConfig.id} (type: ${agentType})`);
+                }
+            }
+            return agents;
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            console.error(`[AgentLoader] Failed to load agents from ${agentsDirectory}: ${msg}`);
+            return [];
+        }
+    }
+    parseMarkdownWithFrontmatter(content) {
+        const match = content.match(/^---([\s\S]*?)---([\s\S]*)$/);
+        if (!match)
+            return { frontmatter: null, body: content };
+        const yamlContent = match[1];
+        const body = match[2];
+        try {
+            const frontmatter = {};
+            for (const line of yamlContent.split(/\r?\n/)) {
+                const trimmed = line.trim();
+                if (!trimmed || trimmed.startsWith("#"))
+                    continue;
+                const colonIdx = trimmed.indexOf(":");
+                if (colonIdx === -1)
+                    continue;
+                const key = trimmed.slice(0, colonIdx).trim();
+                let value = trimmed.slice(colonIdx + 1).trim();
+                // Parse arrays: [a, b, c]
+                if (typeof value === "string" && value.startsWith("[") && value.endsWith("]")) {
+                    value = value
+                        .slice(1, -1)
+                        .split(",")
+                        .map((s) => s.trim().replace(/^["']|["']$/g, ""))
+                        .filter(Boolean);
+                }
+                // Unquote strings
+                if (typeof value === "string") {
+                    value = value.replace(/^["']|["']$/g, "");
+                }
+                frontmatter[key] = value;
+            }
+            return { frontmatter, body: body.trim() };
+        }
+        catch {
+            return { frontmatter: null, body: content };
+        }
+    }
+}

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

@@ -0,0 +1,17 @@
+import type { Agent, AgentConfig } from "./Agent.js";
+import type { LLMProvider } from "./LLMProvider.js";
+import type { MessageBus } from "./MessageBus.js";
+export type AgentConstructor = new (config: AgentConfig, bus: MessageBus, llm?: LLMProvider) => Agent;
+/**
+ * AgentRegistry maintains a mapping of agent 'types' to their concrete class
+ * implementations. This allows the AgentLoader to instantiate the correct class
+ * based on the YAML definition.
+ */
+export declare const AgentRegistry: {
+    /** Register an agent class for a given type name. */
+    register(type: string, agentConstructor: AgentConstructor): void;
+    /** Get the constructor for a given agent type. */
+    get(type: string): AgentConstructor | undefined;
+    /** List all registered agent types. */
+    list(): string[];
+};

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

@@ -0,0 +1,20 @@
+const registry = new Map();
+/**
+ * AgentRegistry maintains a mapping of agent 'types' to their concrete class
+ * implementations. This allows the AgentLoader to instantiate the correct class
+ * based on the YAML definition.
+ */
+export const AgentRegistry = {
+    /** Register an agent class for a given type name. */
+    register(type, agentConstructor) {
+        registry.set(type, agentConstructor);
+    },
+    /** Get the constructor for a given agent type. */
+    get(type) {
+        return registry.get(type);
+    },
+    /** List all registered agent types. */
+    list() {
+        return Array.from(registry.keys());
+    },
+};