@melaya/runner 1.1.61 → 1.1.62

package/dist/assistantFiles.d.ts

@@ -0,0 +1,29 @@
+export declare const TURN_FILE_MAX_BYTES: number;
+export declare const TURN_FILES_MAX = 5;
+export declare const TURN_FILES_MAX_BYTES: number;
+/** Mirror of the server's RUNNER_FILE_EXTS. */
+export declare const TURN_FILE_EXTS: ReadonlySet<string>;
+export interface TurnFileState {
+    dir: string;
+    sent: number;
+    bytes: number;
+    names: Set<string>;
+}
+/** The output dir of one Assistant turn (created). The turn id becomes a safe
+ *  folder name; `base` is for tests. */
+export declare function turnOutputDir(turnId: string, base?: string): string;
+export declare function newTurnFileState(dir: string): TurnFileState;
+export type TurnFileResult = {
+    ok: true;
+    file: {
+        name: string;
+        ext: string;
+        size: number;
+        b64: string;
+    };
+} | {
+    ok: false;
+    reason: string;
+};
+/** Read one file the host reported for this turn, under the rules above. */
+export declare function readTurnFile(state: TurnFileState, reportedPath: unknown): TurnFileResult;

package/dist/assistantFiles.js

@@ -0,0 +1,113 @@
+// Files the runner-hosted Assistant's agent writes during a turn (assistant
+// protocol 4): the runner, not the Python host, decides what leaves this
+// computer.
+//
+// A turn the server marks `fileDelivery` gets its own output dir
+// (<home>/Documents/Melaya-Pipelines/Melaya Assistant/outputs/<turn>), handed to
+// the host as MELAYA_OUTPUT_DIR for that turn: every file-producing tool resolves
+// its path there (shared/runtime/tool_meta.resolve_output_path). When the turn
+// ends the host lists the files it finds there as `file` frames {name, path}.
+// The runner then reads a file only when:
+//   - its real path is INSIDE that turn's dir (no `..`, no symlink out, no
+//     other turn's dir, no other folder of the computer),
+//   - it is a regular file with an allowed extension (documents, sheets, decks,
+//     PDFs, text exports, images, audio / video, archives; no HTML, SVG,
+//     scripts or executables),
+//   - it is at most 25 MB, at most 5 files and 50 MB per turn,
+// and relays {name, ext, size, b64} to the server on the session's own socket.
+// The server re-checks the same caps and stages the bytes for the turn's user
+// (server/src/services/agents/assistantFiles.ts). The files also stay on the
+// computer. A turn without `fileDelivery` (older server) keeps today's
+// behaviour: no per-turn dir, nothing relayed.
+import { closeSync, fstatSync, lstatSync, mkdirSync, openSync, readSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, isAbsolute, join, relative, sep } from "node:path";
+export const TURN_FILE_MAX_BYTES = 25 * 1024 * 1024;
+export const TURN_FILES_MAX = 5;
+export const TURN_FILES_MAX_BYTES = 50 * 1024 * 1024;
+/** Mirror of the server's RUNNER_FILE_EXTS. */
+export const TURN_FILE_EXTS = new Set([
+    "docx", "doc", "odt", "rtf", "xlsx", "xls", "ods", "csv", "tsv", "pptx", "ppt", "odp", "pdf",
+    "txt", "md", "json", "ics", "png", "jpg", "jpeg", "gif", "webp", "mp3", "wav", "mp4", "zip",
+]);
+/** The output dir of one Assistant turn (created). The turn id becomes a safe
+ *  folder name; `base` is for tests. */
+export function turnOutputDir(turnId, base = join(homedir(), "Documents", "Melaya-Pipelines", "Melaya Assistant", "outputs")) {
+    const safe = String(turnId || "").replace(/[^A-Za-z0-9._-]/g, "_").replace(/\.{2,}/g, "_").replace(/^\.+/, "").slice(0, 80) || `turn-${Date.now()}`;
+    const dir = join(base, safe);
+    mkdirSync(dir, { recursive: true });
+    return dir;
+}
+export function newTurnFileState(dir) {
+    return { dir, sent: 0, bytes: 0, names: new Set() };
+}
+const inside = (root, p) => {
+    const rel = relative(root, p);
+    return !!rel && !rel.startsWith("..") && !isAbsolute(rel) && rel.split(sep)[0] !== "..";
+};
+/** Read one file the host reported for this turn, under the rules above. */
+export function readTurnFile(state, reportedPath) {
+    if (state.sent >= TURN_FILES_MAX)
+        return { ok: false, reason: "too_many_files" };
+    const raw = typeof reportedPath === "string" ? reportedPath : "";
+    if (!raw || raw.length > 4096 || raw.includes("\u0000"))
+        return { ok: false, reason: "bad_path" };
+    let root;
+    let real;
+    try {
+        root = realpathSync(state.dir);
+        const candidate = isAbsolute(raw) ? raw : join(state.dir, raw);
+        // A symlink is refused outright (even one pointing inside the dir).
+        if (lstatSync(candidate).isSymbolicLink())
+            return { ok: false, reason: "symlink" };
+        real = realpathSync(candidate);
+    }
+    catch {
+        return { ok: false, reason: "not_found" };
+    }
+    if (!inside(root, real))
+        return { ok: false, reason: "outside_turn_dir" };
+    const name = basename(real);
+    const dot = name.lastIndexOf(".");
+    const ext = dot > 0 ? name.slice(dot + 1).toLowerCase() : "";
+    if (!ext || !TURN_FILE_EXTS.has(ext))
+        return { ok: false, reason: "extension_not_allowed" };
+    if (state.names.has(real))
+        return { ok: false, reason: "duplicate" };
+    let fd = -1;
+    try {
+        fd = openSync(real, "r");
+        const st = fstatSync(fd);
+        if (!st.isFile())
+            return { ok: false, reason: "not_a_file" };
+        if (st.size <= 0)
+            return { ok: false, reason: "empty" };
+        if (st.size > TURN_FILE_MAX_BYTES)
+            return { ok: false, reason: "too_large" };
+        if (state.bytes + st.size > TURN_FILES_MAX_BYTES)
+            return { ok: false, reason: "turn_too_large" };
+        const buf = Buffer.alloc(st.size);
+        let off = 0;
+        while (off < st.size) {
+            const n = readSync(fd, buf, off, st.size - off, off);
+            if (n <= 0)
+                break;
+            off += n;
+        }
+        state.sent += 1;
+        state.bytes += off;
+        state.names.add(real);
+        return { ok: true, file: { name, ext, size: off, b64: buf.subarray(0, off).toString("base64") } };
+    }
+    catch {
+        return { ok: false, reason: "unreadable" };
+    }
+    finally {
+        if (fd >= 0) {
+            try {
+                closeSync(fd);
+            }
+            catch { /* already closed */ }
+        }
+    }
+}

package/dist/assistantHost.py

@@ -399,7 +399,10 @@ _RESERVED_ENV = frozenset({
     "PYTHONPATH", "PYTHONHOME", "PYTHONIOENCODING", "PYTHONUTF8", "SSL_CERT_FILE",
     "REQUESTS_CA_BUNDLE", "LAYA_LOCAL_URL", "LMSTUDIO_BASE_URL", "OLLAMA_BASE_URL",
 })
-_ALLOWED_MEL_ENV = frozenset({"MEL_LUMA_BROWSER_URL", "MEL_LUMA_BROWSER_TOKEN"})
+# Obsidian vaults: the turn's capability, the local relay URL and the selection
+# (for the prompt only), installed and purged per turn like any connector env.
+_ALLOWED_MEL_ENV = frozenset({"MEL_LUMA_BROWSER_URL", "MEL_LUMA_BROWSER_TOKEN",
+                              "MEL_VAULT_CAP", "MEL_VAULT_API_URL", "MEL_VAULT_SELECTION"})
 _LIVE = {
     "lock": threading.RLock(),
     "toolkit": None,          # the lazy toolkit (set_lazy_connectors target)
@@ -675,6 +678,71 @@ def _emit(turn_id: str, kind: str, **fields) -> None:
         pass
 
 
+# ── Output files (assistant protocol 4) ──────────────────────────────────────
+# A turn frame may carry `output_dir`: a fresh folder the runner made for THIS
+# turn. It becomes MELAYA_OUTPUT_DIR for the turn, so every file-producing tool
+# (word / excel / pptx / pdf / chart / image tools, via
+# shared.runtime.tool_meta.resolve_output_path) writes there, and the previous
+# value is restored after the turn. Before `done` the host lists the regular
+# files it finds there as `file` frames {name, path}. It never reads or sends the
+# bytes: the runner (packages/runner/src/assistantFiles.ts) checks the path is
+# inside that dir, applies the extension and size caps and relays the file. No
+# `output_dir` (older server or runner): nothing changes.
+_TURN_FILES = {"dir": "", "prev": None}
+_TURN_FILES_LIST_MAX = 20
+
+
+def _apply_turn_output_dir(req) -> None:
+    d = req.get("output_dir") if isinstance(req, dict) else None
+    if not (isinstance(d, str) and d.strip() and os.path.isdir(d)):
+        _TURN_FILES["dir"] = ""
+        return
+    _TURN_FILES["dir"] = d
+    _TURN_FILES["prev"] = os.environ.get("MELAYA_OUTPUT_DIR")
+    os.environ["MELAYA_OUTPUT_DIR"] = d
+
+
+def _clear_turn_output_dir() -> None:
+    if not _TURN_FILES["dir"]:
+        return
+    prev = _TURN_FILES["prev"]
+    if prev is None:
+        os.environ.pop("MELAYA_OUTPUT_DIR", None)
+    else:
+        os.environ["MELAYA_OUTPUT_DIR"] = prev
+    _TURN_FILES["dir"] = ""
+    _TURN_FILES["prev"] = None
+
+
+def _emit_turn_files(turn_id: str) -> int:
+    """`file` frames for the files in this turn's output dir (oldest first)."""
+    root = _TURN_FILES["dir"]
+    if not root:
+        return 0
+    found: list = []
+    try:
+        for dirpath, dirs, files in os.walk(root, followlinks=False):
+            dirs[:] = [x for x in dirs if not x.startswith(".")]
+            for name in files:
+                p = os.path.join(dirpath, name)
+                if name.startswith(".") or os.path.islink(p) or not os.path.isfile(p):
+                    continue
+                try:
+                    found.append((os.path.getmtime(p), p, name))
+                except OSError:
+                    continue
+            if len(found) > 200:
+                break
+    except Exception:
+        return 0
+    found.sort()
+    n = 0
+    for _mt, p, name in found[:_TURN_FILES_LIST_MAX]:
+        _emit(turn_id, "file", name=name, path=p)
+        n += 1
+    return n
+
+
 def _split_stream_blocks(content):
     """Split a streamed message's content into (answer_text, thinking_text,
     [(tool_id, tool_name)]).
@@ -1480,6 +1548,7 @@ def _run_turn(agent, turn_id: str, message: str, browser_turn: bool = False, ima
         # that named neither what broke nor where. Reported 2026-09-03: two turns
         # in a row with no cause anywhere on screen.
         _emit(turn_id, "error", message=_turn_error_message(exc))
+        _emit_turn_files(turn_id)  # v4: before done, so the stream route stages them
         _emit(turn_id, "done")
         return
 
@@ -1487,6 +1556,7 @@ def _run_turn(agent, turn_id: str, message: str, browser_turn: bool = False, ima
         _stream["turnId"] = ""
         _log("turn cancelled by user STOP")
         _emit(turn_id, "text", content="Stopped.")
+        _emit_turn_files(turn_id)  # v4: before done, so the stream route stages them
         _emit(turn_id, "done")
         return
 
@@ -1497,6 +1567,7 @@ def _run_turn(agent, turn_id: str, message: str, browser_turn: bool = False, ima
             "This browser task ran past its time budget and was stopped. "
             "Ask again with a narrower step, or split it into two."
         ))
+        _emit_turn_files(turn_id)  # v4: before done, so the stream route stages them
         _emit(turn_id, "done")
         return
 
@@ -1510,6 +1581,7 @@ def _run_turn(agent, turn_id: str, message: str, browser_turn: bool = False, ima
     # once a browser-driving turn finishes cleanly.
     if _stream.get("usedBrowser"):
         _emit(turn_id, "browser_done", ok=True)
+    _emit_turn_files(turn_id)  # v4: before done, so the stream route stages them
     _emit(turn_id, "done")
 
 
@@ -1730,9 +1802,12 @@ def main() -> int:
         # ALWAYS purge it — success, error, or cancel — so no reusable grant
         # ever survives in the warm host environment.
         browser_turn = _apply_browser_turn_grant(req)
+        # v4: this turn's output dir (absent: unchanged behaviour).
+        _apply_turn_output_dir(req)
         try:
             _run_turn(agent, turn_id, message, browser_turn=browser_turn, images=images)
         finally:
+            _clear_turn_output_dir()
             _purge_browser_turn_grant()
             # Connector credentials live for the turn only; the selection (ids,
             # no secret) stays and the next frame re-sends the env.

package/dist/cli.js

@@ -189,6 +189,13 @@ async function bootstrap() {
         await copilotLogin();
         return;
     }
+    // `melaya-runner obsidian-rest` — connect a vault's Obsidian Local REST API
+    // by hand; the key is typed here and never leaves this computer.
+    if (process.argv[2] === "obsidian-rest") {
+        const { obsidianRestCli } = await import("./obsidianAppCli.js");
+        await obsidianRestCli();
+        return;
+    }
     await main();
 }
 bootstrap().catch(async (e) => {

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;
@@ -61,7 +70,12 @@ const RESERVED_BROWSER_ENV = ["MEL_BROWSER_URL", "MEL_BROWSER_TOKEN"];
 // 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).
-const ASSISTANT_PROTOCOL_VERSION = 3;
+// 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";
@@ -150,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;
@@ -346,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,
@@ -358,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})`));
             }
@@ -998,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.
@@ -1513,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") {
@@ -2125,12 +2240,32 @@ export async function connect(opts) {
                 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;
@@ -2194,6 +2329,9 @@ export async function connect(opts) {
                 // 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) {
@@ -2299,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 };
+}