@melaya/runner 1.1.60 → 1.1.62

package/dist/connection.js

@@ -17,7 +17,7 @@ import { spawn } from "child_process";
 import { writeFileSync, mkdirSync, existsSync, readFileSync, copyFileSync } from "fs";
 import { dirname, join } from "path";
 import { fileURLToPath } from "url";
-import { tmpdir, homedir } from "os";
+import { tmpdir, homedir, hostname } from "os";
 import { createHash, createHmac, timingSafeEqual } from "crypto";
 import { startLocalRelay, setActiveProject } from "./localRelay.js";
 // ESM equivalent of __dirname — required for the rag:ingest handler to
@@ -34,6 +34,15 @@ import { verifyBrowserGrant, createInMemoryReplayStore, loadPinnedPublicKeysFrom
 import { discoverEngines } from "./browserProvisioner.js";
 import { getRunnerDeviceId } from "./sessionManager.js";
 import { scrubTriggeredEnv } from "./triggerEnv.js";
+import { pickNativeFolder } from "./folderPicker.js";
+import { newTurnFileState, readTurnFile, turnOutputDir } from "./assistantFiles.js";
+// Obsidian vault host (docs/plans/obsidian-vault-protocol.md): device vaults
+// registered on this computer, served after the runner verifies each
+// capability itself.
+import { VAULT_HOST_CAPABILITY, VaultHostProcess, VaultRegistry, VaultService, attachVaultSocketHandlers, findVaultHostScript, setVaultRelayPort, vaultToolEnv, trustRunVaultCapability, } from "./vaults.js";
+// Obsidian app bridge: App ops through the user's running Obsidian (CLI /
+// Local REST API); the REST key stays in ~/.melaya-runner/vaults.
+import { ObsidianAppBridge } from "./obsidianApp.js";
 // Same ceiling the builder enforces on RunRequest.trigger (48 KB UTF-8 of the
 // compact JSON) and the server dispatch route re-checks (Buffer.byteLength).
 const MAX_TRIGGER_JSON_BYTES = 48 * 1024;
@@ -54,7 +63,19 @@ const RESERVED_BROWSER_ENV = ["MEL_BROWSER_URL", "MEL_BROWSER_TOKEN"];
 // versioned ready/hello). The server enforces a MINIMUM: a runner advertising a
 // lower protocol never gets an assistant session routed to it (it gets a clear
 // "update your runner" instead of a silent stale-memory turn).
-const ASSISTANT_PROTOCOL_VERSION = 2;
+// v3: per-turn connectors. The server boots the host WITHOUT connectors (and
+// without their credentials) when it sees v3, sends the chat's selection + env
+// on every runner:assistant_turn frame, and pushes mid-turn changes (autonomy
+// mode, connectors) with runner:assistant_turn_update. Changing a connector or
+// the autonomy mode never reboots the host, and a warm spare stays adoptable
+// whatever the selection. A v2 server keeps sending connectors at boot; this
+// runner then behaves exactly as before (turnConnectors absent).
+// v4: output files. A turn frame with `fileDelivery` gets a per-turn output dir
+// (MELAYA_OUTPUT_DIR for that turn); the files the agent wrote there are relayed
+// to the server as `file` frames with their bytes, under the caps and path
+// confinement of assistantFiles.ts. A server that does not send `fileDelivery`
+// gets exactly the v3 behaviour (files stay on this computer only).
+const ASSISTANT_PROTOCOL_VERSION = 4;
 // Best-effort read of our own package version (mirrors cli.ts). Advertised in the
 // hello so the server can log / gate on a package floor too.
 let RUNNER_VERSION = "0.0.0";
@@ -143,6 +164,63 @@ export async function connect(opts) {
     // is refused (plan Section 4 binding rule).
     let socketGeneration = 0;
     const runnerDeviceId = getRunnerDeviceId();
+    // ── Obsidian vault host ───────────────────────────────────────────────
+    // Registrations persist in ~/.melaya-runner/vaults/registry.json; the
+    // Python host (localVault.py, engine from the shared bundle) starts lazily
+    // on the first register/op, or now when vaults are already registered.
+    const vaultRegistry = new VaultRegistry();
+    vaultRegistry.load();
+    const vaultLog = (m) => { if (opts.verbose)
+        console.log(chalk.gray(`  [vaults] ${m}`)); };
+    const vaultHost = new VaultHostProcess({
+        wanted: () => vaultRegistry.list().length > 0,
+        log: vaultLog,
+        launch: async () => {
+            const { ensurePythonEnv, getCertBundlePath } = await import("./pythonEnv.js");
+            const { getLocalSharedVersion } = await import("./sharedVendor.js");
+            let localVersion = getLocalSharedVersion();
+            if (!localVersion) {
+                await ensureSharedModules(opts.serverUrl, "latest", opts.token);
+                localVersion = getLocalSharedVersion();
+            }
+            if (!localVersion)
+                throw new Error("runner python runtime still setting up");
+            const env = await ensurePythonEnv(opts.pythonPath, localVersion, (m) => vaultLog(`venv: ${m}`));
+            if (!env.ok)
+                throw new Error(`venv bootstrap failed: ${env.reason}`);
+            const script = findVaultHostScript(__dirname);
+            if (!script)
+                throw new Error("localVault.py not found — update @melaya/runner");
+            mkdirSync(vaultRegistry.dir, { recursive: true, mode: 0o700 });
+            const certBundle = getCertBundlePath();
+            return {
+                pythonPath: env.pythonPath,
+                scriptPath: script,
+                cwd: vaultRegistry.dir,
+                env: {
+                    ...process.env,
+                    PYTHONPATH: getSharedDir(),
+                    PYTHONIOENCODING: "utf-8",
+                    PYTHONUTF8: "1",
+                    ...(certBundle ? { SSL_CERT_FILE: certBundle, REQUESTS_CA_BUNDLE: certBundle } : {}),
+                },
+            };
+        },
+    });
+    const vaultService = new VaultService({
+        rnrId: runnerDeviceId,
+        registry: vaultRegistry,
+        host: vaultHost,
+        serverHttpBase: opts.serverUrl.replace(/^wss:/, "https:").replace(/^ws:/, "http:"),
+        emitStatus: (ev) => { if (socket.connected)
+            socket.emit("runner:vault-status", ev); },
+        log: vaultLog,
+        app: new ObsidianAppBridge({ dir: vaultRegistry.dir, log: vaultLog }),
+    });
+    attachVaultSocketHandlers(socket, vaultService, () => pickNativeFolder("Select your Obsidian vault folder"));
+    if (vaultRegistry.list().length) {
+        void vaultService.restore().catch((e) => vaultLog(`restore failed: ${e?.message || e}`));
+    }
     const _ensureBrowserBridge = async () => {
         if (browserBridge)
             return browserBridge;
@@ -339,7 +417,9 @@ export async function connect(opts) {
             // event_triggers_v1: this runner writes payload.triggerJson to
             // <runDir>/trigger.json + MEL_TRIGGER_FILE. The server reports
             // triggerAccepted from it; older runners silently drop the block.
-            capabilities: ["assistant_session", `browser_control_v${BROWSER_CONTROL_VERSION}`, EVENT_TRIGGERS_CAPABILITY],
+            // vault_host_v1: this runner hosts Obsidian vaults on this computer
+            // (runner:vault-* events); the server then pushes runner:vaultKeys.
+            capabilities: ["assistant_session", `browser_control_v${BROWSER_CONTROL_VERSION}`, EVENT_TRIGGERS_CAPABILITY, VAULT_HOST_CAPABILITY],
             package: "@melaya/runner",
             version: RUNNER_VERSION,
             assistantProtocol: ASSISTANT_PROTOCOL_VERSION,
@@ -351,10 +431,22 @@ export async function connect(opts) {
                 cdp: true,
                 engines: browserEngines,
             },
+            // Device vaults bind to this stable install id (protocol §3).
+            vaultHost: {
+                runnerDevice: runnerDeviceId,
+                deviceName: hostname(),
+                platform: process.platform,
+            },
         });
+        // Index statuses produced while disconnected (or before this socket).
+        for (const ev of vaultService.latestStatuses())
+            socket.emit("runner:vault-status", ev);
         // Start local event relay
         if (!relay) {
-            relay = await startLocalRelay(socket, opts.verbose, opts.serverUrl);
+            relay = await startLocalRelay(socket, opts.verbose, opts.serverUrl, {
+                vaultOp: (req, res) => vaultService.handleRelayHttp(req, res),
+            });
+            setVaultRelayPort(relay.port);
             if (opts.verbose) {
                 console.log(chalk.gray(`  [relay] Listening on 127.0.0.1:${relay.port} (nonce: ${relay.nonce})`));
             }
@@ -991,6 +1083,19 @@ export async function connect(opts) {
                 ...(isTriggeredRun
                     ? { MEL_HITL_APPROVAL_TTL_S: String(triggerApprovalTtl) }
                     : {}),
+                // Obsidian vaults, reserved LAST: the capability the server issued for
+                // this run on this computer, served by the local relay (a vault on this
+                // computer is read in place, any other through Melaya). A credential
+                // can never replace these names.
+                MEL_VAULT_CAP: "",
+                MEL_VAULT_API_URL: "",
+                ...(() => {
+                    const cap = typeof payload.vaultCapability === "string"
+                        ? String(payload.vaultCapability)
+                        : "";
+                    trustRunVaultCapability(cap);
+                    return vaultToolEnv(cap);
+                })(),
             };
             // Surface the tier to the chat panel as a system message so the
             // operator sees WHY a small model is running with tighter caps.
@@ -1506,6 +1611,23 @@ export async function connect(opts) {
                         console.log(chalk.gray(`  [assistant-stdout] ${t.slice(0, mi)}`));
                     try {
                         const parsed = JSON.parse(t.slice(mi + _EVENT_PREFIX.length));
+                        // v4 output file: the host only names a path; the runner reads it
+                        // (confined to the turn's dir, capped) and relays the bytes. A frame
+                        // for a turn without fileDelivery, or a refused file, is dropped:
+                        // the raw path never leaves this computer.
+                        if (parsed?.kind === "file") {
+                            const st = session.turnFiles?.get(String(parsed.turnId || ""));
+                            if (st && session.forward) {
+                                const r = readTurnFile(st, parsed.path);
+                                if (r.ok)
+                                    socket.emit("runner:assistant_event", { sessionId: session.sid, turnId: String(parsed.turnId), kind: "file", ...r.file });
+                                else if (opts.verbose)
+                                    console.log(chalk.gray(`  [assistant] output file not relayed (${r.reason})`));
+                            }
+                            continue;
+                        }
+                        if (parsed?.kind === "done" && typeof parsed.turnId === "string")
+                            session.turnFiles?.delete(parsed.turnId);
                         if (typeof parsed?.memoryWatermark === "number")
                             session.memoryWatermark = parsed.memoryWatermark;
                         if (parsed?.kind === "ready") {
@@ -1515,11 +1637,20 @@ export async function connect(opts) {
                                 session.configHash = parsed.configHash;
                             session.ready = true;
                             parsed.protocol = ASSISTANT_PROTOCOL_VERSION;
+                            // A spare adopted while still booting reports the generation it
+                            // booted under; the session's is the one the adopt frame set.
+                            if (session.forward)
+                                parsed.generation = session.generation;
                         }
                         // A spare's frames are NOT forwarded (no session yet); adoption flips
                         // session.forward and re-emits `ready` with the real sid.
                         if (session.forward)
                             socket.emit("runner:assistant_event", { sessionId: session.sid, ...parsed });
+                        // A session host is up: NOW the warm spare may boot. Booting both at
+                        // once made them compile + import the shared bundle concurrently
+                        // (prod 2026-10-11, Windows: ~50 s each instead of ~7 s).
+                        if (parsed?.kind === "ready" && session.forward)
+                            schedulePrewarm();
                     }
                     catch {
                         // The literal "MELASSIST " appeared inside raw text (not a real frame)
@@ -1594,11 +1725,17 @@ export async function connect(opts) {
     // turns it off.
     const WARM_POOL_ENABLED = process.env.MEL_ASSISTANT_WARM_POOL !== "0";
     let _prewarmInFlight = false;
+    // Never while a session host is booting (it would compete for the same cold
+    // import of the shared bundle): the session's `ready` frame schedules it.
+    const _sessionHostBooting = () => bootingAssistants.size > 0 || [...activeAssistants.values()].some((s) => s.forward && !s.ready);
     const schedulePrewarm = () => {
         if (!WARM_POOL_ENABLED || !warmSpareSeed || _prewarmInFlight)
             return;
+        if (_sessionHostBooting())
+            return;
         if (warmSpare) {
-            if (warmSpare.configHash && warmSpare.configHash !== warmSpareSeed.configHash) {
+            const spareHash = warmSpare.configHash || warmSpare.seedConfigHash || "";
+            if (spareHash && spareHash !== warmSpareSeed.configHash) {
                 try {
                     warmSpare.proc.kill();
                 }
@@ -1624,6 +1761,7 @@ export async function connect(opts) {
             const spareEnv = { ...seed.env };
             const spare = launchAssistantHost({ env: spareEnv, pythonPath: seed.pythonPath, workDir: wd, stagedHost: staged, sid: `__spare__:${stamp}`, generation: seed.generation, forward: false, providerLabel: "prewarm" });
             spare.credHash = seed.credHash;
+            spare.seedConfigHash = seed.configHash;
             warmSpare = spare;
             const t = setTimeout(() => { if (warmSpare === spare && !spare.forward) {
                 try {
@@ -1688,7 +1826,12 @@ export async function connect(opts) {
             // Connector tool sets the user enabled for this chat (comma-joined service
             // ids). The host seeds a lazy toolkit from these so ANY connector's tools
             // are reachable without exploding context.
-            MEL_ASSISTANT_CONNECTORS: Array.isArray(payload.connectors) ? payload.connectors.join(",") : "",
+            // Per-turn connectors (v3): empty at boot, the turn frame carries them.
+            MEL_ASSISTANT_CONNECTORS: !payload.turnConnectors && Array.isArray(payload.connectors) ? payload.connectors.join(",") : "",
+            // Tells the host to take connectors per turn (lazy registry scope + env
+            // per turn, connector rule in the per-turn prompt). Part of its config
+            // hash ("turn-connectors-v1"), byte-aligned with the server.
+            MEL_ASSISTANT_TURN_CONNECTORS: payload.turnConnectors ? "1" : "",
             // Surgical tool pinning: exact connector tool NAMES (not just service ids)
             // the server already resolved creds for. The host registers these ACTIVE
             // at boot instead of dumping them into the deferred pool, eliminating the
@@ -1696,7 +1839,8 @@ export async function connect(opts) {
             // Byte-for-byte source of truth for _config_hash's pinned-tools field.
             MEL_ASSISTANT_PINNED_TOOLS: payload.pinnedTools?.join(",") ?? "",
             // Gate write connector-tools behind the in-chat approval card (fail-safe).
-            MEL_ASSISTANT_CONNECTOR_HITL: Array.isArray(payload.connectors) && payload.connectors.length ? "1" : "",
+            // Per-turn mode: the host arms it itself whenever a turn selects a connector.
+            MEL_ASSISTANT_CONNECTOR_HITL: !payload.turnConnectors && Array.isArray(payload.connectors) && payload.connectors.length ? "1" : "",
             // HITL autonomy mode ("safe" | "autonomous" | "payments_only"). The host
             // reads this at start; each turn's frame can flip it (see assistant_turn).
             // Fail-safe: unknown ⇒ "safe".
@@ -1849,12 +1993,17 @@ export async function connect(opts) {
         // conversation's via an `adopt` frame, so a restored conversation's
         // generation-bound rehydrate still applies (the old exact-generation match
         // meant a spare could almost never be adopted).
+        // A spare that is STILL BOOTING with the same seed config + credentials is
+        // adopted too: the session waits for ITS ready frame (forwarded under this
+        // sid once `forward` flips) instead of booting a second host next to it.
         if (!activeAssistants.has(sid) && !bootingAssistants.has(sid)
-            && warmSpare && warmSpare.ready && !warmSpare.killed && expectedConfig
-            && warmSpare.configHash === expectedConfig && (warmSpare.memoryWatermark || 0) === 0
+            && warmSpare && !warmSpare.killed && expectedConfig
+            && (warmSpare.ready ? warmSpare.configHash : warmSpare.seedConfigHash) === expectedConfig
+            && (warmSpare.memoryWatermark || 0) === 0
             && warmSpare.credHash === _assistantCredHash(payload.credentials)) {
             const spare = warmSpare;
             warmSpare = null;
+            // Queued on the host's stdin: a booting host reads it right after `ready`.
             try {
                 spare.proc.stdin?.write(JSON.stringify({ kind: "adopt", generation }) + "\n");
             }
@@ -1864,9 +2013,14 @@ export async function connect(opts) {
             spare.forward = true;
             spare.lastActivity = Date.now();
             activeAssistants.set(sid, spare);
-            console.log(chalk.green(`  ◆ Assistant ${sid.slice(0, 10)}… adopted warm spare — cold boot skipped`));
-            emitEv({ kind: "ready", memoryWatermark: spare.memoryWatermark || 0, generation: spare.generation, hostInstanceId: spare.hostInstanceId, configHash: spare.configHash, protocol: ASSISTANT_PROTOCOL_VERSION });
-            schedulePrewarm(); // refill the pool for the next session
+            if (spare.ready) {
+                console.log(chalk.green(`  ◆ Assistant ${sid.slice(0, 10)}… adopted warm spare — cold boot skipped`));
+                emitEv({ kind: "ready", memoryWatermark: spare.memoryWatermark || 0, generation: spare.generation, hostInstanceId: spare.hostInstanceId, configHash: spare.configHash, protocol: ASSISTANT_PROTOCOL_VERSION });
+                schedulePrewarm(); // refill the pool for the next session
+            }
+            else {
+                console.log(chalk.green(`  ◆ Assistant ${sid.slice(0, 10)}… adopted the warm spare still booting, no second host`));
+            }
             return;
         }
         // A boot is already in flight for this sid (concurrent start / server restart
@@ -1904,7 +2058,7 @@ export async function connect(opts) {
             // Cloudflare's write-bot rule. Without it the tool falls back to aiohttp,
             // which 403s ("cloudflare_mitigation" / "velocity_throttled") on every RSVP.
             // Idempotent + best-effort; only paid when luma is actually selected.
-            if (Array.isArray(payload.connectors) && payload.connectors.includes("luma")) {
+            if (!payload.turnConnectors && Array.isArray(payload.connectors) && payload.connectors.includes("luma")) {
                 await _ensureLumaBridge();
             }
             const env = await buildAssistantEnv(payload, sid, generation);
@@ -1917,7 +2071,7 @@ export async function connect(opts) {
             // matching spare for the NEXT new session — which then adopts it and skips
             // the cold boot (see the ADOPTION fast path + schedulePrewarm above).
             warmSpareSeed = { env, configHash: expectedConfig, generation, pythonPath: envResult.pythonPath, workDirBase: tmpdir(), hostScript, credHash: _assistantCredHash(payload.credentials) };
-            schedulePrewarm();
+            // The spare boots once this session reports ready (see the stdout parser).
         }
         catch (e) {
             emitEv({ kind: "error", message: `assistant start failed: ${e?.message || e}` });
@@ -2076,6 +2230,42 @@ export async function connect(opts) {
             if (opts.verbose)
                 console.log(chalk.gray(`  [browser-bridge] ext-proxy turn (session=${payload.sessionId.slice(0, 10)} url=${turnBridgeUrl})`));
         }
+        // Per-turn connectors (v3). Luma writes go through the local browser bridge
+        // (Cloudflare write rule): bring it up when this turn selects luma, and hand
+        // its url/token to the host with luma's env for the turn.
+        const turnConnectors = Array.isArray(payload.connectors) ? payload.connectors.filter((c) => typeof c === "string") : null;
+        const turnConnectorEnv = {};
+        if (turnConnectors) {
+            for (const [svc, env] of Object.entries(payload.connectorEnv || {})) {
+                if (env && typeof env === "object")
+                    turnConnectorEnv[svc] = { ...env };
+            }
+            // Obsidian vaults: the server sends only the capability; the local relay
+            // serves vaults on this computer and forwards the rest to Melaya.
+            if (turnConnectorEnv.obsidian?.MEL_VAULT_CAP) {
+                trustRunVaultCapability(turnConnectorEnv.obsidian.MEL_VAULT_CAP);
+                turnConnectorEnv.obsidian = { ...turnConnectorEnv.obsidian, ...vaultToolEnv(turnConnectorEnv.obsidian.MEL_VAULT_CAP) };
+            }
+            if (turnConnectors.includes("luma")) {
+                await _ensureLumaBridge().catch(() => { });
+                if (lumaBridge)
+                    turnConnectorEnv.luma = { ...(turnConnectorEnv.luma || {}), MEL_LUMA_BROWSER_URL: lumaBridge.url, MEL_LUMA_BROWSER_TOKEN: lumaBridge.token };
+            }
+        }
+        // v4 output files: a fresh dir for this turn (MELAYA_OUTPUT_DIR in the host
+        // for the turn); its files are relayed at turn end (stdout `file` frames).
+        let turnOutDir = "";
+        if (payload.fileDelivery === true && payload.turnId) {
+            try {
+                turnOutDir = turnOutputDir(String(payload.turnId));
+                (s.turnFiles ??= new Map()).set(String(payload.turnId), newTurnFileState(turnOutDir));
+            }
+            catch (e) {
+                turnOutDir = "";
+                if (opts.verbose)
+                    console.log(chalk.gray(`  [assistant] no output dir for this turn: ${e?.message || e}`));
+            }
+        }
         // Capture for the stdout "done" handler closure below.
         const _turnBridgeRunId = turnBridgeRunId;
         const _turnId = payload.turnId;
@@ -2136,6 +2326,12 @@ export async function connect(opts) {
                 ...(turnBridgeUrl && turnBridgeToken
                     ? { mel_browser_url: turnBridgeUrl, mel_browser_token: turnBridgeToken }
                     : {}),
+                // v3 per-turn connectors (absent from a v2 server: the host keeps its
+                // boot-time connectors).
+                ...(turnConnectors ? { connectors: turnConnectors, connector_env: turnConnectorEnv } : {}),
+                // v4: the turn's output dir (absent: the host keeps its boot-time dir
+                // and reports no files).
+                ...(turnOutDir ? { output_dir: turnOutDir } : {}),
             }) + "\n");
         }
         catch (e) {
@@ -2148,6 +2344,28 @@ export async function connect(opts) {
             socket.emit("runner:assistant_event", { sessionId: payload.sessionId, turnId: payload.turnId, kind: "error", message: `turn write failed: ${e?.message || e}` });
         }
     });
+    // v3 live mid-turn update: the user changed the autonomy mode or the connector
+    // selection while the reply streams. The host's stdin reader applies it
+    // between tool calls (like STOP), so the NEXT tool call of the running turn
+    // uses it; a pending approval stays pending. Ignored for any other turn.
+    socket.on("runner:assistant_turn_update", (payload) => {
+        const s = activeAssistants.get(String(payload?.sessionId || ""));
+        if (!s || !payload?.turnId)
+            return;
+        s.lastActivity = Date.now();
+        const frame = { kind: "turn_update", turnId: payload.turnId };
+        if (typeof payload.hitlMode === "string") {
+            frame.hitl_mode = (payload.hitlMode === "autonomous" || payload.hitlMode === "payments_only") ? payload.hitlMode : "safe";
+        }
+        if (Array.isArray(payload.connectors)) {
+            frame.connectors = payload.connectors.filter((c) => typeof c === "string");
+            frame.connector_env = payload.connectorEnv && typeof payload.connectorEnv === "object" ? payload.connectorEnv : {};
+        }
+        try {
+            s.proc.stdin?.write(JSON.stringify(frame) + "\n");
+        }
+        catch { /* best-effort */ }
+    });
     socket.on("runner:assistant_stop", (payload) => {
         const s = activeAssistants.get(String(payload.sessionId || ""));
         if (s) {
@@ -2219,60 +2437,13 @@ export async function connect(opts) {
             socket.emit("runner:pick-folder-result", { session_id: sid, ok, path, error });
         };
         try {
-            const { execFile } = await import("child_process");
-            const platform = process.platform;
-            const run = (cmd, args) => new Promise((resolve, reject) => {
-                execFile(cmd, args, { maxBuffer: 1024 * 64 }, (err, stdout, stderr) => {
-                    if (err) {
-                        const out = (stdout || "").trim();
-                        const errMsg = (stderr || err.message || "").trim();
-                        // osascript returns code 1 when user cancels — empty stdout
-                        if (!out && /User canceled|cancelled/i.test(errMsg))
-                            return resolve("");
-                        return reject(new Error(errMsg || "pick failed"));
-                    }
-                    resolve((stdout || "").trim());
-                });
-            });
-            let picked = "";
-            if (platform === "darwin") {
-                // osascript returns "Macintosh HD:Users:me:Documents" — convert to POSIX
-                const raw = await run("osascript", [
-                    "-e", 'tell application "System Events"',
-                    "-e", "activate",
-                    "-e", "set p to choose folder with prompt \"Select your reference docs folder\"",
-                    "-e", "end tell",
-                    "-e", "return POSIX path of p",
-                ]);
-                picked = raw.replace(/\/$/, "");
-            }
-            else if (platform === "win32") {
-                const ps = [
-                    "Add-Type -AssemblyName System.Windows.Forms;",
-                    "$f = New-Object System.Windows.Forms.FolderBrowserDialog;",
-                    "$f.Description = 'Select your reference docs folder';",
-                    "$f.ShowNewFolderButton = $true;",
-                    "if ($f.ShowDialog() -eq 'OK') { [Console]::Out.Write($f.SelectedPath) }",
-                ].join(" ");
-                picked = await run("powershell", ["-NoProfile", "-STA", "-Command", ps]);
-            }
-            else {
-                // Linux — try zenity, fall back to error if missing
-                picked = await run("zenity", [
-                    "--file-selection", "--directory",
-                    "--title=Select your reference docs folder",
-                ]);
-            }
-            if (!picked)
+            const r = await pickNativeFolder("Select your reference docs folder");
+            if (!("path" in r))
                 return reply(false, null, "cancelled");
-            reply(true, picked);
+            reply(true, r.path);
         }
         catch (e) {
-            const msg = String(e?.message || "pick failed");
-            const hint = /ENOENT|not found|spawn/i.test(msg) && process.platform === "linux"
-                ? "Install 'zenity' (apt install zenity) or type the path manually."
-                : "";
-            reply(false, null, hint ? `${msg} — ${hint}` : msg);
+            reply(false, null, String(e?.message || "pick failed"));
         }
     });
     socket.on("rag:ingest", async (payload) => {

package/dist/folderPicker.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Native OS folder dialog, shared by runner:pick-folder (static-context / RAG
+ * folders) and runner:vault-pick-folder (Obsidian vaults).
+ *
+ * Browsers can't reveal absolute paths for security, so the runner — which
+ * lives on the user's box — pops the dialog. Mac: osascript. Windows:
+ * PowerShell WinForms. Linux: zenity. Fixed argv; the prompt is a constant
+ * chosen by the caller, never user or model input.
+ */
+export type FolderPickResult = {
+    path: string;
+} | {
+    cancelled: true;
+};
+export declare function pickNativeFolder(prompt: string): Promise<FolderPickResult>;

package/dist/folderPicker.js

@@ -0,0 +1,69 @@
+/**
+ * Native OS folder dialog, shared by runner:pick-folder (static-context / RAG
+ * folders) and runner:vault-pick-folder (Obsidian vaults).
+ *
+ * Browsers can't reveal absolute paths for security, so the runner — which
+ * lives on the user's box — pops the dialog. Mac: osascript. Windows:
+ * PowerShell WinForms. Linux: zenity. Fixed argv; the prompt is a constant
+ * chosen by the caller, never user or model input.
+ */
+import { execFile } from "child_process";
+export async function pickNativeFolder(prompt) {
+    const platform = process.platform;
+    const run = (cmd, args) => new Promise((resolve, reject) => {
+        execFile(cmd, args, { maxBuffer: 1024 * 64 }, (err, stdout, stderr) => {
+            if (err) {
+                const out = (stdout || "").trim();
+                const errMsg = (stderr || err.message || "").trim();
+                // osascript returns code 1 when user cancels — empty stdout
+                if (!out && /User canceled|cancelled/i.test(errMsg))
+                    return resolve("");
+                return reject(new Error(errMsg || "pick failed"));
+            }
+            resolve((stdout || "").trim());
+        });
+    });
+    // Quotes would break out of the AppleScript / PowerShell string literal.
+    const safePrompt = prompt.replace(/["'`$\\]/g, "");
+    let picked = "";
+    try {
+        if (platform === "darwin") {
+            // osascript returns "Macintosh HD:Users:me:Documents" — convert to POSIX
+            const raw = await run("osascript", [
+                "-e", 'tell application "System Events"',
+                "-e", "activate",
+                "-e", `set p to choose folder with prompt "${safePrompt}"`,
+                "-e", "end tell",
+                "-e", "return POSIX path of p",
+            ]);
+            picked = raw.replace(/\/$/, "");
+        }
+        else if (platform === "win32") {
+            const ps = [
+                "Add-Type -AssemblyName System.Windows.Forms;",
+                "$f = New-Object System.Windows.Forms.FolderBrowserDialog;",
+                `$f.Description = '${safePrompt}';`,
+                "$f.ShowNewFolderButton = $true;",
+                "if ($f.ShowDialog() -eq 'OK') { [Console]::Out.Write($f.SelectedPath) }",
+            ].join(" ");
+            picked = await run("powershell", ["-NoProfile", "-STA", "-Command", ps]);
+        }
+        else {
+            // Linux — try zenity, fall back to error if missing
+            picked = await run("zenity", [
+                "--file-selection", "--directory",
+                `--title=${safePrompt}`,
+            ]);
+        }
+    }
+    catch (e) {
+        const msg = String(e?.message || "pick failed");
+        const hint = /ENOENT|not found|spawn/i.test(msg) && process.platform === "linux"
+            ? "Install 'zenity' (apt install zenity) or type the path manually."
+            : "";
+        throw new Error(hint ? `${msg} — ${hint}` : msg);
+    }
+    if (!picked)
+        return { cancelled: true };
+    return { path: picked };
+}

package/dist/localRelay.d.ts

@@ -9,6 +9,7 @@
  *   - Per-run nonce required in the URL path to prevent injection from
  *     other processes on the same machine
  */
+import http from "http";
 import type { Socket } from "socket.io-client";
 export interface LocalRelay {
     port: number;
@@ -16,4 +17,10 @@ export interface LocalRelay {
     close: () => void;
 }
 export declare function setActiveProject(project: string): void;
-export declare function startLocalRelay(socket: Socket, verbose: boolean, serverUrl?: string): Promise<LocalRelay>;
+export interface LocalRelayRoutes {
+    /** POST /vaults/op (Obsidian vault tools, protocol §2). Authenticated by the
+     *  vault capability in `Authorization: Vault <cap>`, not by the nonce: the
+     *  handler verifies it (local device vaults) or forwards it to the server. */
+    vaultOp?: (req: http.IncomingMessage, res: http.ServerResponse) => Promise<void> | void;
+}
+export declare function startLocalRelay(socket: Socket, verbose: boolean, serverUrl?: string, routes?: LocalRelayRoutes): Promise<LocalRelay>;

package/dist/localRelay.js

@@ -55,7 +55,7 @@ function _flushThrottle(socket, verbose) {
     _throttleQueue = [];
     _throttleTimer = null;
 }
-export function startLocalRelay(socket, verbose, serverUrl) {
+export function startLocalRelay(socket, verbose, serverUrl, routes = {}) {
     const nonce = crypto.randomUUID().replace(/-/g, "");
     return new Promise((resolve, reject) => {
         const expectedPath = `/events/relay/${nonce}`;
@@ -147,6 +147,26 @@ export function startLocalRelay(socket, verbose, serverUrl) {
                 });
                 return;
             }
+            // ── Obsidian vault ops (docs/plans/obsidian-vault-protocol.md §2) ──
+            if (req.method === "POST" && req.url && /^\/vaults\/op\/?(\?.*)?$/.test(req.url)) {
+                if (!routes.vaultOp) {
+                    res.writeHead(404);
+                    res.end("Not found");
+                    return;
+                }
+                Promise.resolve(routes.vaultOp(req, res)).catch(() => {
+                    if (res.headersSent) {
+                        try {
+                            res.end();
+                        }
+                        catch { /* closed */ }
+                        return;
+                    }
+                    res.writeHead(500, { "Content-Type": "application/json" });
+                    res.end('{"ok":false,"error":"relay_failed"}');
+                });
+                return;
+            }
             if (req.method !== "POST" || req.url !== expectedPath) {
                 res.writeHead(404);
                 res.end("Not found");