pi-vault-mind 0.8.0 → 0.8.3

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

@@ -0,0 +1,19 @@
+/**
+ * MinerAgent — knowledge extraction and storage agent.
+ *
+ * Allowed tools: read, write, edit, grep, find, ls, vm_search, vm_fts_search, vm_append
+ * Write collections: main, research
+ * Cannot publish (vm_sync disabled).
+ */
+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 MinerAgent 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/MinerAgent.js

@@ -0,0 +1,70 @@
+/**
+ * MinerAgent — knowledge extraction and storage agent.
+ *
+ * Allowed tools: read, write, edit, grep, find, ls, vm_search, vm_fts_search, vm_append
+ * Write collections: main, research
+ * Cannot publish (vm_sync disabled).
+ */
+import { Agent } from "../agent-bus/Agent.js";
+export class MinerAgent 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 !== "miner")
+            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 Miner agent. Task: ${job.instruction}\n\nSource file: ${job.filePath}\n\nExtract entities and relationships, then store them via vm_append. 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: `> Miner extracted findings. See dispatch ${job.dispatchId}.`,
+                },
+            ],
+        });
+    }
+    async tick() {
+        // Event-driven — work arrives via JOB_AVAILABLE subscription
+    }
+}

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

@@ -0,0 +1,4 @@
+export { HeavyLifterAgent, type DispatchJob } from "./HeavyLifterAgent.js";
+export { MinerAgent } from "./MinerAgent.js";
+export { BroadcasterAgent } from "./BroadcasterAgent.js";
+export { ManagerAgent } from "./ManagerAgent.js";

package/dist/src/agents/index.js

@@ -0,0 +1,4 @@
+export { HeavyLifterAgent } from "./HeavyLifterAgent.js";
+export { MinerAgent } from "./MinerAgent.js";
+export { BroadcasterAgent } from "./BroadcasterAgent.js";
+export { ManagerAgent } from "./ManagerAgent.js";

package/dist/src/auth.d.ts

@@ -4,7 +4,7 @@
  * Token resolution order:
  *   1. `process.env.PVM_API_TOKEN`
  *   2. `<homedir>/.pi/agent/vault-mind.env` (key=value, # comments)
- *   3. `wiki.embedding.modal.apiToken` in the loaded config
+ *   3. `vaultMind.embedding.modal.apiToken` in the loaded config
  *
  * Returns `null` if no token is configured (auth is off until set).
  *
@@ -15,6 +15,21 @@
 import type { UniversalConfig } from "./types.js";
 /** Resolve the bearer token. `cfg` is optional; pass the loaded config to fall back to it. */
 export declare const resolveAuthToken: (cfg?: UniversalConfig) => string | null;
+/** Resolved identity for a per-role bearer token. */
+export interface TokenIdentity {
+    token: string;
+    /** Lowercase role name, e.g. "manager", "miner". */
+    identity: string;
+    /** Same as identity; reserved for future role-vs-identity distinction. */
+    role: string;
+}
+/**
+ * Scan `PVM_TOKEN_<ROLE>` env vars and return the identity whose token
+ * matches `token` via constant-time compare.  Returns `undefined` when
+ * no per-role token matches (caller should fall back to the legacy
+ * `PVM_API_TOKEN` path).
+ */
+export declare const resolveTokenIdentity: (token: string) => TokenIdentity | undefined;
 export interface IncomingLike {
     headers: {
         authorization?: string | string[] | undefined;
@@ -23,8 +38,40 @@ export interface IncomingLike {
 export interface AuthResult {
     ok: boolean;
     reason?: "missing" | "malformed" | "mismatch";
+    /** Resolved per-role identity when a `PVM_TOKEN_*` token matched. */
+    identity?: TokenIdentity;
 }
-/** Authorize a request against the resolved token. Returns `ok: true` if auth is off (no token configured). */
+/**
+ * Authorize a request against configured tokens.
+ *
+ * Resolution order:
+ * 1. Per-role `PVM_TOKEN_<ROLE>` env vars — returns the matched identity.
+ * 2. Legacy `PVM_API_TOKEN` — returns `ok: true` with no identity (full access).
+ * 3. No token configured → `ok: true` (auth is off).
+ */
 export declare const authoriseRequest: (req: IncomingLike, cfg?: UniversalConfig) => AuthResult;
 /** Test-only: forget the cached token so tests get a fresh resolve on each call. */
 export declare const _resetAuthCache: () => void;
+/** Set an in-memory token override for the current process. Invalidates any cached value. */
+export declare const setToken: (value: string) => void;
+/** Clear the in-memory token cache. Equivalent to `_resetAuthCache` but with a public name. */
+export declare const clearToken: () => void;
+/**
+ * Revoke a role-specific bearer token by removing `PVM_TOKEN_<IDENTITY>`
+ * from `~/.pi/agent/vault-mind.env`. Preserves all other lines and comments.
+ * Returns `true` if the variable was found and removed.
+ */
+export declare const revokeToken: (identity: string) => boolean;
+/**
+ * Generate a fresh 32-byte base64url token, persist it to
+ * `<os.homedir()>/.pi/agent/vault-mind.env` (replacing any existing
+ * `PVM_API_TOKEN` line while preserving all other lines and comments), create
+ * the directory + file if missing, apply `chmod 600` (best-effort; no-op on
+ * win32), update the in-process cache, and return the new token.
+ *
+ * **Env-var precedence note:** if `PVM_API_TOKEN` is exported as an environment
+ * variable it takes precedence over the dotenv file at resolution time, so the
+ * rotated token only becomes active once the env override is unset and the
+ * process is restarted (or the in-process cache is refreshed via `setToken`).
+ */
+export declare const rotateToken: () => string;

package/dist/src/auth.js

@@ -4,7 +4,7 @@
  * Token resolution order:
  *   1. `process.env.PVM_API_TOKEN`
  *   2. `<homedir>/.pi/agent/vault-mind.env` (key=value, # comments)
- *   3. `wiki.embedding.modal.apiToken` in the loaded config
+ *   3. `vaultMind.embedding.modal.apiToken` in the loaded config
  *
  * Returns `null` if no token is configured (auth is off until set).
  *
@@ -12,6 +12,7 @@
  * dotenv file is the caller's responsibility and is a no-op on
  * win32 (the file system doesn't honor POSIX modes there).
  */
+import * as crypto from "node:crypto";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
@@ -41,7 +42,7 @@ const readDotenvToken = () => {
     return null;
 };
 const readConfigToken = (cfg) => {
-    return cfg?.wiki?.embedding?.modal?.apiToken;
+    return cfg?.vaultMind?.embedding?.modal?.apiToken;
 };
 /** Resolve the bearer token. `cfg` is optional; pass the loaded config to fall back to it. */
 export const resolveAuthToken = (cfg) => {
@@ -61,6 +62,32 @@ export const resolveAuthToken = (cfg) => {
     }
     return null;
 };
+/**
+ * Scan `PVM_TOKEN_<ROLE>` env vars and return the identity whose token
+ * matches `token` via constant-time compare.  Returns `undefined` when
+ * no per-role token matches (caller should fall back to the legacy
+ * `PVM_API_TOKEN` path).
+ */
+export const resolveTokenIdentity = (token) => {
+    for (const [key, value] of Object.entries(process.env)) {
+        const m = key.match(/^PVM_TOKEN_([A-Z][A-Z0-9_]*)$/);
+        if (!m || !value)
+            continue;
+        if (safeEqual(value, token)) {
+            const role = m[1].toLowerCase();
+            return { token: value, identity: role, role };
+        }
+    }
+    return undefined;
+};
+/** True when any PVM_TOKEN_<ROLE> env var is set. */
+const hasAnyPerRoleToken = () => {
+    for (const key of Object.keys(process.env)) {
+        if (/^PVM_TOKEN_[A-Z][A-Z0-9_]*$/.test(key))
+            return true;
+    }
+    return false;
+};
 /** Constant-time compare to avoid timing attacks on the bearer token. */
 const safeEqual = (a, b) => {
     if (a.length !== b.length)
@@ -71,19 +98,40 @@ const safeEqual = (a, b) => {
     }
     return mismatch === 0;
 };
-/** Authorize a request against the resolved token. Returns `ok: true` if auth is off (no token configured). */
+/**
+ * Authorize a request against configured tokens.
+ *
+ * Resolution order:
+ * 1. Per-role `PVM_TOKEN_<ROLE>` env vars — returns the matched identity.
+ * 2. Legacy `PVM_API_TOKEN` — returns `ok: true` with no identity (full access).
+ * 3. No token configured → `ok: true` (auth is off).
+ */
 export const authoriseRequest = (req, cfg) => {
-    const expected = resolveAuthToken(cfg);
-    if (!expected)
-        return { ok: true };
     const raw = req.headers.authorization;
     const header = Array.isArray(raw) ? raw[0] : raw;
+    // Auth off: no tokens configured at all → allow everything
+    const hasPerRole = resolveTokenIdentity("") !== undefined || true; // check env vars
+    const hasLegacy = resolveAuthToken(cfg) !== null;
+    if (!hasLegacy && !hasAnyPerRoleToken()) {
+        // No tokens configured — auth is off, allow all requests
+        if (!header)
+            return { ok: true };
+    }
     if (!header)
         return { ok: false, reason: "missing" };
     const m = header.match(/^Bearer\s+(.+)$/i);
     if (!m)
         return { ok: false, reason: "malformed" };
-    if (!safeEqual(m[1], expected))
+    const token = m[1];
+    // 1. Per-role token match
+    const identity = resolveTokenIdentity(token);
+    if (identity)
+        return { ok: true, identity };
+    // 2. Legacy single-token fallback
+    const expected = resolveAuthToken(cfg);
+    if (!expected)
+        return { ok: true }; // auth off — no tokens configured
+    if (!safeEqual(token, expected))
         return { ok: false, reason: "mismatch" };
     return { ok: true };
 };
@@ -91,3 +139,97 @@ export const authoriseRequest = (req, cfg) => {
 export const _resetAuthCache = () => {
     cached = null;
 };
+/** Set an in-memory token override for the current process. Invalidates any cached value. */
+export const setToken = (value) => {
+    cached = { value };
+};
+/** Clear the in-memory token cache. Equivalent to `_resetAuthCache` but with a public name. */
+export const clearToken = () => {
+    cached = null;
+};
+/**
+ * Revoke a role-specific bearer token by removing `PVM_TOKEN_<IDENTITY>`
+ * from `~/.pi/agent/vault-mind.env`. Preserves all other lines and comments.
+ * Returns `true` if the variable was found and removed.
+ */
+export const revokeToken = (identity) => {
+    const varName = `PVM_TOKEN_${identity.toUpperCase()}`;
+    const dotenvPath = path.join(os.homedir(), DOTENV_REL);
+    let lines = [];
+    try {
+        lines = fs.readFileSync(dotenvPath, "utf-8").split(/\r?\n/);
+    }
+    catch {
+        return false;
+    }
+    const lineRe = /^\s*([A-Z_][A-Z0-9_]*)\s*=\s*("([^"]*)"|'([^']*)'|[^\s#]+)/;
+    let removed = false;
+    const updated = [];
+    for (const line of lines) {
+        const m = line.match(lineRe);
+        if (!removed && m && m[1] === varName) {
+            removed = true;
+            continue;
+        }
+        updated.push(line);
+    }
+    if (!removed)
+        return false;
+    let content = updated.join("\n");
+    if (!content.endsWith("\n"))
+        content += "\n";
+    fs.writeFileSync(dotenvPath, content, "utf-8");
+    return true;
+};
+/**
+ * Generate a fresh 32-byte base64url token, persist it to
+ * `<os.homedir()>/.pi/agent/vault-mind.env` (replacing any existing
+ * `PVM_API_TOKEN` line while preserving all other lines and comments), create
+ * the directory + file if missing, apply `chmod 600` (best-effort; no-op on
+ * win32), update the in-process cache, and return the new token.
+ *
+ * **Env-var precedence note:** if `PVM_API_TOKEN` is exported as an environment
+ * variable it takes precedence over the dotenv file at resolution time, so the
+ * rotated token only becomes active once the env override is unset and the
+ * process is restarted (or the in-process cache is refreshed via `setToken`).
+ */
+export const rotateToken = () => {
+    const newToken = crypto.randomBytes(32).toString("base64url");
+    const dotenvPath = path.join(os.homedir(), DOTENV_REL);
+    const dir = path.dirname(dotenvPath);
+    if (!fs.existsSync(dir))
+        fs.mkdirSync(dir, { recursive: true });
+    let existingLines = [];
+    try {
+        existingLines = fs.readFileSync(dotenvPath, "utf-8").split(/\r?\n/);
+    }
+    catch {
+        // file missing — start fresh
+    }
+    const tokenLine = `PVM_API_TOKEN="${newToken}"`;
+    let replaced = false;
+    const updatedLines = [];
+    for (const line of existingLines) {
+        if (!replaced && /^\s*PVM_API_TOKEN\s*=/.test(line)) {
+            updatedLines.push(tokenLine);
+            replaced = true;
+        }
+        else {
+            updatedLines.push(line);
+        }
+    }
+    if (!replaced)
+        updatedLines.push(tokenLine);
+    let content = updatedLines.join("\n");
+    if (!content.endsWith("\n"))
+        content += "\n";
+    fs.writeFileSync(dotenvPath, content, "utf-8");
+    try {
+        fs.chmodSync(dotenvPath, 0o600);
+    }
+    catch {
+        // no-op on win32 or when chmod is unavailable
+    }
+    cached = { value: newToken };
+    return newToken;
+};

package/dist/src/autosync.d.ts

@@ -1,7 +1,7 @@
 /**
  * Optional background vector sync (off by default).
  *
- * When `wiki.embedding.modal.sync.autoSync` is true, a background interval pulls
+ * When `vaultMind.embedding.modal.sync.autoSync` is true, a background interval pulls
  * new server-side vectors into the local LanceDB on a configurable cadence so
  * search keeps working with the latest embeddings. It is guarded by config and
  * safe to leave disabled — if Modal is not configured or auto-sync is off, the

package/dist/src/autosync.js

@@ -1,7 +1,7 @@
 /**
  * Optional background vector sync (off by default).
  *
- * When `wiki.embedding.modal.sync.autoSync` is true, a background interval pulls
+ * When `vaultMind.embedding.modal.sync.autoSync` is true, a background interval pulls
  * new server-side vectors into the local LanceDB on a configurable cadence so
  * search keeps working with the latest embeddings. It is guarded by config and
  * safe to leave disabled — if Modal is not configured or auto-sync is off, the
@@ -20,10 +20,10 @@ export const startAutoSync = (intervalMs = 300_000) => {
     const tick = async () => {
         try {
             const cfg = loadConfig(process.cwd());
-            const sync = cfg.wiki.embedding.modal?.sync;
+            const sync = cfg.vaultMind.embedding.modal?.sync;
             if (!sync?.autoSync)
                 return; // off by default
-            if (!isModalConfigured(cfg.wiki))
+            if (!isModalConfigured(cfg.vaultMind))
                 return; // nothing to sync
             const ms = sync.autoSyncIntervalMs ?? intervalMs;
             void ms; // cadence is fixed at start; tick honors config toggle

package/dist/src/bridge.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Embedded pi-agent-bus bridge for pi-vault-mind.
+ *
+ * Adapted from pi-agent-bus-bridge/index.ts. Provides:
+ * - Per-agent tool allowlist enforcement (not global exposedPiTools)
+ * - Synchronous execution of both built-in SDK tools and vm_* extension tools
+ * - Tool cache scoped by agent working directory
+ * - MessageBus integration for agent→tool→agent communication
+ *
+ * Vendored from kylebrodeur/pi-agent-bus (MIT).
+ */
+import { type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { MessageBus } from "./agent-bus/MessageBus.js";
+export interface AgentIdentity {
+    id: string;
+    role: string;
+    allowedTools: string[];
+    writeCollections: string[];
+    canPublish: boolean;
+    workingDir?: string;
+    /** Vault-relative path prefixes this identity may write/edit files within. Empty or absent = no restriction. */
+    allowedVaultPaths?: string[];
+    /** Allowed outbound hosts for bash egress. Undefined/empty = allow all (backwards compat). */
+    egressAllowlist?: string[];
+    /** Visibility for entries written by this identity. "vault" = private to this vault, "public" = visible to all. Defaults to "vault". */
+    visibility?: string;
+    /** Collections this role may read from. Empty or absent = no restriction. */
+    readCollections?: string[];
+}
+/** Register an agent's identity for tool gating. Called by the engine after loading agents. */
+export declare function registerAgentIdentity(identity: AgentIdentity): void;
+/** Remove an agent's identity. */
+export declare function unregisterAgentIdentity(agentId: string): void;
+/** Check whether a tool is allowed for a given agent. */
+export declare function isToolAllowed(agentId: string, toolName: string): boolean;
+/** Get an agent's identity. */
+export declare function getAgentIdentity(agentId: string): AgentIdentity | undefined;
+export declare function createBridge(pi: ExtensionAPI, bus: MessageBus): void;
+type ExtensionToolHandler = (args: Record<string, unknown>, identity: AgentIdentity | undefined, isAutopilot?: boolean) => Promise<unknown>;
+/**
+ * Register a handler for an extension tool (vm_*).
+ * Call this in index.ts after registering tools with pi.
+ */
+export declare function registerExtensionToolHandler(toolName: string, handler: ExtensionToolHandler): void;
+export {};

package/dist/src/bridge.js

@@ -0,0 +1,189 @@
+/**
+ * Embedded pi-agent-bus bridge for pi-vault-mind.
+ *
+ * Adapted from pi-agent-bus-bridge/index.ts. Provides:
+ * - Per-agent tool allowlist enforcement (not global exposedPiTools)
+ * - Synchronous execution of both built-in SDK tools and vm_* extension tools
+ * - Tool cache scoped by agent working directory
+ * - MessageBus integration for agent→tool→agent communication
+ *
+ * Vendored from kylebrodeur/pi-agent-bus (MIT).
+ */
+import * as path from "node:path";
+import { createBashTool, createEditTool, createFindTool, createGrepTool, createLsTool, createReadTool, createWriteTool, } from "@earendil-works/pi-coding-agent";
+// ── Path-scope helpers ───────────────────────────────────────────────────────
+/**
+ * Return true if `filePath` (absolute or relative to `cwd`) is within at
+ * least one of the `allowedPrefixes`. Handles `..` escapes via path.resolve.
+ */
+function isPathWithinAllowed(filePath, cwd, allowedPrefixes) {
+    const resolved = path.resolve(cwd, filePath);
+    return allowedPrefixes.some((prefix) => {
+        const base = path.resolve(cwd, prefix);
+        return resolved === base || resolved.startsWith(base + path.sep);
+    });
+}
+// ── State ────────────────────────────────────────────────────────────────────
+const toolCache = new Map();
+const agentIdentities = new Map();
+// ── Tool factories ───────────────────────────────────────────────────────────
+function createBuiltInTools(cwd) {
+    return {
+        read: createReadTool(cwd),
+        bash: createBashTool(cwd),
+        edit: createEditTool(cwd),
+        write: createWriteTool(cwd),
+        find: createFindTool(cwd),
+        grep: createGrepTool(cwd),
+        ls: createLsTool(cwd),
+    };
+}
+function getBuiltInTools(cwd) {
+    let tools = toolCache.get(cwd);
+    if (!tools) {
+        tools = createBuiltInTools(cwd);
+        toolCache.set(cwd, tools);
+    }
+    return tools;
+}
+// ── Agent identity registry ──────────────────────────────────────────────────
+/** Register an agent's identity for tool gating. Called by the engine after loading agents. */
+export function registerAgentIdentity(identity) {
+    agentIdentities.set(identity.id, identity);
+}
+/** Remove an agent's identity. */
+export function unregisterAgentIdentity(agentId) {
+    agentIdentities.delete(agentId);
+}
+/** Check whether a tool is allowed for a given agent. */
+export function isToolAllowed(agentId, toolName) {
+    const identity = agentIdentities.get(agentId);
+    if (!identity)
+        return false;
+    return identity.allowedTools.includes(toolName);
+}
+/** Get an agent's identity. */
+export function getAgentIdentity(agentId) {
+    return agentIdentities.get(agentId);
+}
+// ── Bridge ───────────────────────────────────────────────────────────────────
+/**
+ * Create the tool bridge on a MessageBus.
+ *
+ * Subscribes to `pi_tool_bridge_requests`, validates against per-agent
+ * allowlists, executes tools synchronously, and publishes results back.
+ *
+ * Extension tools (vm_*) are executed via a handler registry — call
+ * `registerExtensionToolHandler()` to wire them up.
+ */
+// ── Egress host parsing ──────────────────────────────────────────────────────
+/**
+ * Extract outbound hostnames from a bash command string.
+ * Handles URLs (http/https/ftp), git SSH-style (git@host:path),
+ * and scp-style (user@host:path) patterns.
+ * Returns unique, lowercased hostnames.
+ */
+function parseHostsFromCommand(command) {
+    const hosts = new Set();
+    // Standard URLs: scheme://host[:port][/path]
+    const urlRe = /[a-zA-Z][a-zA-Z0-9+.-]*:\/\/([^/\s"'`$<>|&;()]+)/g;
+    for (const m of command.matchAll(urlRe)) {
+        // Strip trailing port if present
+        const host = m[1].replace(/:\d+$/, "");
+        if (host.length > 0)
+            hosts.add(host.toLowerCase());
+    }
+    // Git SSH-style: git@host:path
+    const gitSshRe = /git@([a-zA-Z0-9][a-zA-Z0-9.-]*[a-zA-Z0-9]):/g;
+    for (const m of command.matchAll(gitSshRe)) {
+        hosts.add(m[1].toLowerCase());
+    }
+    // scp-style: user@host:path (not email addresses — requires path-like after colon)
+    const scpRe = /(?:^|\s)([a-zA-Z0-9._%+-]+)@([a-zA-Z0-9][a-zA-Z0-9.-]*[a-zA-Z0-9]):(?:\/|~|[a-zA-Z0-9])/g;
+    for (const m of command.matchAll(scpRe)) {
+        hosts.add(m[2].toLowerCase());
+    }
+    return [...hosts];
+}
+export function createBridge(pi, bus) {
+    bus.subscribe("pi_tool_bridge_requests", async (message) => {
+        const payload = message.payload;
+        const { requestId, agentId, toolName, args, responseTopic } = payload;
+        let result;
+        let error;
+        // 1. Check per-agent allowlist
+        if (!isToolAllowed(agentId, toolName)) {
+            error = `Tool '${toolName}' is not allowed for agent '${agentId}'.`;
+        }
+        else {
+            try {
+                const identity = agentIdentities.get(agentId);
+                const cwd = identity?.workingDir ?? process.cwd();
+                // 2. Try built-in SDK tools first
+                const builtInTools = getBuiltInTools(cwd);
+                const builtIn = builtInTools[toolName];
+                if (builtIn) {
+                    // 2a. Enforce writable-path scope for write/edit tools.
+                    // read/bash/grep/find/ls are unaffected.
+                    if ((toolName === "write" || toolName === "edit") &&
+                        identity?.allowedVaultPaths &&
+                        identity.allowedVaultPaths.length > 0) {
+                        const targetPath = typeof args.path === "string" ? args.path : undefined;
+                        if (!targetPath || !isPathWithinAllowed(targetPath, cwd, identity.allowedVaultPaths)) {
+                            error = `Write to '${targetPath ?? "(no path)"}' denied for agent '${agentId}': path is not within allowed vault paths [${identity.allowedVaultPaths.join(", ")}].`;
+                        }
+                    }
+                    // 2b. Enforce egress allowlist for Heavy-Lifter bash calls.
+                    if (!error &&
+                        toolName === "bash" &&
+                        identity?.role === "heavy-lifter" &&
+                        identity?.egressAllowlist &&
+                        identity.egressAllowlist.length > 0) {
+                        const command = typeof args.command === "string" ? args.command : "";
+                        const hosts = parseHostsFromCommand(command);
+                        for (const host of hosts) {
+                            if (!identity.egressAllowlist.includes(host)) {
+                                error = `Heavy-Lifter cannot reach '${host}'. Allowed: ${identity.egressAllowlist.join(", ")}`;
+                                break;
+                            }
+                        }
+                    }
+                    // 2c. Gate Heavy-Lifter bash for autopilot forks (destructive operation).
+                    if (!error && toolName === "bash" && identity?.role === "heavy-lifter") {
+                        error =
+                            "This action requires approval. Reason: autopilot forks cannot perform destructive operations without human authorization.";
+                    }
+                    if (!error) {
+                        result = await builtIn.execute(`bridge_${requestId}`, args, new AbortController().signal, () => { });
+                    }
+                }
+                else {
+                    // 3. Try extension tool handlers
+                    const handler = extensionToolHandlers.get(toolName);
+                    if (handler) {
+                        result = await handler(args, identity, true);
+                    }
+                    else {
+                        // 4. Fallback: queue as user message (for tools we haven't wired yet)
+                        pi.sendUserMessage(`Please run tool ${toolName} with args: ${JSON.stringify(args)}`, {
+                            deliverAs: "followUp",
+                        });
+                        result = { queued: true };
+                    }
+                }
+            }
+            catch (e) {
+                error = e instanceof Error ? e.message : String(e);
+            }
+        }
+        await bus.publish(responseTopic, "pi-tool-bridge", { requestId, result, error });
+    });
+}
+const extensionToolHandlers = new Map();
+/**
+ * Register a handler for an extension tool (vm_*).
+ * Call this in index.ts after registering tools with pi.
+ */
+export function registerExtensionToolHandler(toolName, handler) {
+    extensionToolHandlers.set(toolName, handler);
+}

package/dist/src/commands.d.ts

@@ -21,7 +21,7 @@ export declare const planGitignore: (existing: string | null) => {
     content: string;
 };
 export declare const watcherState: import("./watcher.js").WatcherState;
-/** Module-level server state, referenced by the /wiki server command.
+/** Module-level server state, referenced by the /vm server command.
  *  Port is set when the server starts in index.ts. */
 export declare const serverState: ServerState;
 export declare const registerCommands: (pi: ExtensionAPI) => void;