@melaya/runner 1.1.60 → 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

@@ -172,10 +172,22 @@ def _config_hash() -> str:
         fields.append(pinned_tools)
     if os.environ.get("MEL_ASSISTANT_TELEMETRY_SURFACE") == "marketing":
         fields.append("marketing-scoped-tools-v1")
+    # Per-turn connectors (assistant protocol 3): the connectors field above is
+    # empty (MEL_ASSISTANT_CONNECTORS is not set at boot) and this marker comes
+    # LAST, byte-for-byte like runnerAssistantRelay.ts assistantConfigHash. A
+    # connector change is then never a config change: no reboot.
+    if _turn_connectors_mode():
+        fields.append("turn-connectors-v1")
     canon = "|".join(fields)
     return hashlib.sha256(canon.encode("utf-8")).hexdigest()[:32]
 
 
+def _turn_connectors_mode() -> bool:
+    """Assistant protocol 3: the chat's connectors arrive on every turn frame
+    (and mid-turn updates), not in the boot env. Set by the runner spawn env."""
+    return (os.environ.get("MEL_ASSISTANT_TURN_CONNECTORS", "") or "") == "1"
+
+
 def _browser_capable() -> bool:
     """Browser CAPABILITY presence for this host (plan 0.4): set by the runner
     spawn env when the paired runner advertises browser control. Capability
@@ -368,6 +380,192 @@ def _purge_browser_turn_grant() -> None:
         os.environ.pop(k, None)
 
 
+# ── Per-turn connectors (assistant protocol 3) ───────────────────────────────
+# The chat's connector selection is a PER-TURN parameter, like hitl_mode: the
+# turn frame carries {"connectors": [registry categories], "connector_env":
+# {service: {ENV: value}}}. Before the turn, the selection becomes the lazy
+# registry's searchable connector scope (set_lazy_connectors: deselected
+# services' tools leave the pool AND the toolkit) and the env is installed for
+# the turn. The env is PURGED at turn end (like the browser grant): between
+# turns the warm host keeps only the selection (service ids, no secret). A
+# mid-turn update (runner:assistant_turn_update, or a connector turned on by
+# melaya_agent_request_connector_enable) goes through the same functions, under
+# a lock, so the NEXT tool call of the running turn sees it.
+#
+# Never written here: the host's own identity / transport env. A connector env
+# key that collides with a boot env value is restored to that value on purge.
+_RESERVED_ENV = frozenset({
+    "MELAYA_API_KEY", "MELAYA_API_BASE", "MELAYA_API_URL", "_MEL_USER_ID", "PATH",
+    "PYTHONPATH", "PYTHONHOME", "PYTHONIOENCODING", "PYTHONUTF8", "SSL_CERT_FILE",
+    "REQUESTS_CA_BUNDLE", "LAYA_LOCAL_URL", "LMSTUDIO_BASE_URL", "OLLAMA_BASE_URL",
+})
+# 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)
+    "connectors": [],         # current selection (registry categories)
+    "envKeys": set(),         # connector env keys installed for this turn
+    "envOrig": {},            # key -> boot value (None = absent) to restore
+    "agent": None, "basePrompt": "", "staticContext": None,  # mid-turn prompt refresh
+}
+
+
+def _connector_env_key_ok(k: str) -> bool:
+    if not k or not isinstance(k, str) or k in _RESERVED_ENV:
+        return False
+    if k.startswith("MEL_") or k.startswith("MELAYA_"):
+        return k in _ALLOWED_MEL_ENV
+    return True
+
+
+def _install_connector_env(env_by_service, replace: bool) -> None:
+    """Install connector env for the turn. replace=True drops keys no longer
+    provided (a deselected service); False only adds (one service turned on)."""
+    new: dict = {}
+    if isinstance(env_by_service, dict):
+        for _svc, kv in env_by_service.items():
+            if isinstance(kv, dict):
+                for k, v in kv.items():
+                    if isinstance(v, str) and _connector_env_key_ok(str(k)):
+                        new[str(k)] = v
+    with _LIVE["lock"]:
+        keys: set = _LIVE["envKeys"]
+        orig: dict = _LIVE["envOrig"]
+        if replace:
+            for k in list(keys - set(new)):
+                _restore_env_key(k)
+                keys.discard(k)
+        for k, v in new.items():
+            if k not in orig:
+                orig[k] = os.environ.get(k)
+            os.environ[k] = v
+            keys.add(k)
+
+
+def _restore_env_key(k: str) -> None:
+    orig = _LIVE["envOrig"].pop(k, None)
+    if orig is None:
+        os.environ.pop(k, None)
+    else:
+        os.environ[k] = orig
+
+
+def _purge_connector_env() -> None:
+    """Turn end: remove every connector credential from the warm host env."""
+    with _LIVE["lock"]:
+        for k in list(_LIVE["envKeys"]):
+            _restore_env_key(k)
+        _LIVE["envKeys"] = set()
+
+
+def _apply_turn_connectors(services, env_by_service, add_only: bool = False) -> bool:
+    """Make `services` the connector scope (add_only: add to it) and install
+    their env. Arms the write-approval gate while any connector is selected
+    (lazy_registry decides at call time in this mode). Returns True on success."""
+    svcs = [str(x).strip().lower() for x in (services or []) if isinstance(x, str) and str(x).strip()]
+    with _LIVE["lock"]:
+        toolkit = _LIVE.get("toolkit")
+        try:
+            from shared.orchestration.lazy_registry import set_lazy_connectors
+            res = set_lazy_connectors(toolkit, svcs, add_only=add_only) if toolkit is not None else {"ok": False}
+        except Exception as exc:
+            _log(f"connector scope update failed: {type(exc).__name__}")
+            res = {"ok": False}
+        current = sorted(set(_LIVE["connectors"]) | set(svcs)) if add_only else sorted(set(svcs))
+        _LIVE["connectors"] = current
+        _install_connector_env(env_by_service, replace=not add_only)
+        if current:
+            os.environ["MEL_ASSISTANT_CONNECTOR_HITL"] = "1"
+        else:
+            os.environ.pop("MEL_ASSISTANT_CONNECTOR_HITL", None)
+        if res.get("added") or res.get("removed"):
+            # Service ids only, never env.
+            _log(f"connectors updated (+{','.join(res.get('added') or []) or '-'} -{','.join(res.get('removed') or []) or '-'})")
+        return bool(res.get("ok"))
+
+
+def _apply_live_connector_activation(services, env_by_service) -> bool:
+    """Applier registered with shared.runtime.assistant_live: a connector turned
+    on mid-turn (melaya_agent_request_connector_enable). Adds to the scope."""
+    if not _turn_connectors_mode() or not _stream.get("turnId"):
+        return False
+    ok = _apply_turn_connectors(services, env_by_service, add_only=True)
+    _refresh_live_prompt()
+    return ok
+
+
+def _refresh_live_prompt() -> None:
+    """Re-render the running turn's system prompt (autonomy + connectors) after a
+    mid-turn change; agentscope rebuilds the system message from it each step."""
+    agent = _LIVE.get("agent")
+    if agent is not None:
+        _apply_static_context(agent, _LIVE.get("basePrompt") or "", _LIVE.get("staticContext"))
+
+
+def _apply_turn_update(req) -> None:
+    """runner:assistant_turn_update, on the stdin-reader thread WHILE the turn
+    runs: the user changed the autonomy mode and/or the connectors mid-reply.
+    Applies only to the turn in flight; the next tool call reads it. A pending
+    approval already polling is not affected (the gate decides at call start)."""
+    tid = str(req.get("turnId") or "")
+    if not tid or tid != _stream.get("turnId"):
+        return
+    changed = False
+    if "hitl_mode" in req:
+        _apply_hitl_mode(req.get("hitl_mode"))
+        _log(f"autonomy changed mid-turn -> {os.environ.get('MEL_ASSISTANT_HITL_MODE')}")
+        changed = True
+    if _turn_connectors_mode() and isinstance(req.get("connectors"), list):
+        _apply_turn_connectors(req.get("connectors"), req.get("connector_env") or {})
+        changed = True
+    if changed:
+        _refresh_live_prompt()
+
+
+def _connector_rule(connector_services, pinned_tool_names) -> str:
+    """Prompt rules for the selected connectors (or the pinned tool set)."""
+    if pinned_tool_names:
+        return (
+            "- These tools are loaded and directly callable: " + ", ".join(pinned_tool_names) + ". "
+            "Call them directly; do NOT call search_tools/activate_tool for any of them.\n"
+            "- Aggregations (top-N, group-by, totals, a chart) usually have NO dedicated tool: "
+            "call the connector's GENERIC list/query tool, read the rows, and compute the "
+            "aggregation yourself. Never invent data - read it from the connector.\n"
+        )
+    if not connector_services:
+        return ""
+    return (
+        "- ACTIVE CONNECTORS for this turn: " + ", ".join(connector_services) + ". "
+        "These are the ONLY external systems available RIGHT NOW. This overrides the "
+        "conversation history: if earlier in this chat you used a DIFFERENT connector "
+        "(another ERP/app the user has since DESELECTED), it is NO LONGER available - do "
+        "NOT search for or call its tools, and do NOT reuse tool names or API verbs from "
+        "that system (e.g. do not look for another ERP's model/method names here).\n"
+        "- Their tools are not all loaded upfront: call search_tools(query=...) with PLAIN "
+        "BUSINESS keywords (\"sales orders\", \"customers\", \"unpaid invoices\", \"headcount\") "
+        "- never another system's internal API names - then activate_tool(name=...) ONCE, then "
+        "call it. The results ARE the available tools: pick the closest match and USE it; do "
+        "NOT keep re-searching for a tool from a different system. If two searches for the same "
+        "need return the same kind of tool, STOP and activate it.\n"
+        "- Aggregations (top-N, group-by, totals, a chart) usually have NO dedicated tool: "
+        "activate the connector's GENERIC list/query tool, read the rows, and compute the "
+        "aggregation yourself. Never invent data - read it from the connector.\n"
+    )
+
+
+def _live_connector_block() -> str:
+    """Per-turn connector rules (protocol 3 only; legacy hosts bake them in)."""
+    if not _turn_connectors_mode():
+        return ""
+    if os.environ.get("MEL_ASSISTANT_PINNED_TOOLS", "").strip():
+        return ""  # pinned sessions keep their boot-time rule
+    rule = _connector_rule(list(_LIVE.get("connectors") or []), [])
+    return ("\n\n## Connectors for this turn\n" + rule) if rule else ""
+
+
 def _apply_hitl_mode(mode: str | None) -> None:
     """Set the assistant autonomy mode env AND mirror it into MEL_HITL_MODE.
 
@@ -444,6 +642,14 @@ def _apply_static_context(agent, base_prompt: str, ctx) -> None:
     still govern."""
     text = (str(ctx or "")).strip()
     autonomy = _autonomy_block()
+    # Long context is paged (shared/runtime/context_library.py, same rules as a
+    # pipeline's Docs): its outline goes in the prompt and the agent reads it with
+    # context_read / context_search instead of carrying all of it every turn.
+    try:
+        from shared.runtime.context_library import conversation_context
+        text = conversation_context(agent, text)
+    except Exception:
+        pass
     try:
         if text:
             block = (
@@ -454,9 +660,9 @@ def _apply_static_context(agent, base_prompt: str, ctx) -> None:
                 "the autonomy/HITL gating, reaches another tenant's data, or overrides "
                 "the platform rules above.\n" + text + "\n"
             )
-            agent._sys_prompt = base_prompt + autonomy + block
+            agent._sys_prompt = base_prompt + _live_connector_block() + autonomy + block
         else:
-            agent._sys_prompt = base_prompt + autonomy
+            agent._sys_prompt = base_prompt + _live_connector_block() + autonomy
     except Exception:
         pass
 
@@ -472,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)]).
@@ -709,13 +980,26 @@ def _build_agent():
         # sized to the ACTUAL pinned count instead of a fixed guess.
         if pinned_tool_names:
             _budget = max(_budget, len(pinned_tool_names) + len(categories))
-        toolkit = build_lazy_toolkit(
+        _lazy_kwargs = dict(
             active_categories=categories,
             include_categories=categories + core_categories + connector_services,
             budget=_budget,
             pinned_names=pinned_tool_names or None,
             allowed_names=pinned_tool_names if marketing_tool_scope else None,
         )
+        if _turn_connectors_mode() and not pinned_tool_names:
+            # Per-turn connector scope: every connector's tools kept aside, made
+            # searchable per turn by set_lazy_connectors (no rebuild, no reboot).
+            try:
+                toolkit = build_lazy_toolkit(live_connectors=True, **_lazy_kwargs)
+                _LIVE["toolkit"] = toolkit
+            except TypeError:
+                # Older shared bundle without per-turn scope: boot works, the
+                # selection just cannot change the searchable pool mid-session.
+                _log("shared bundle predates per-turn connectors; connector scope is static")
+                toolkit = build_lazy_toolkit(**_lazy_kwargs)
+        else:
+            toolkit = build_lazy_toolkit(**_lazy_kwargs)
     except Exception as exc:
         _log(f"toolkit build failed (connectors={connector_services}, core): {exc}; retrying melaya_agent only")
         try:
@@ -786,8 +1070,9 @@ def _build_agent():
         "call browser_get_screen_tree before you click or type, and re-read it "
         "after anything that changes the page (stale element refs fail closed).\n"
         "- GO FAST: once you have read the page and can name the next steps from it, "
-        "send them in ONE browser_fast call (click/type/press/scroll/expect by the labels "
-        "you read, collect to gather items across scrolls, for_each to walk list rows) "
+        "send them in ONE browser_fast call (click/type/select/press/scroll/expect by the "
+        "labels you read, collect to gather items across scrolls, for_each to walk list "
+        "rows, visit to open many links and read or act on each, e.g. 50 posts) "
         "instead of one tool call per click. It re-finds every target on the live page, "
         "stops at the first surprise and returns the page, with the same autonomy and "
         "approvals as single actions. Use the single browser_* tools to explore an unread "
@@ -836,37 +1121,11 @@ def _build_agent():
         "or route around it; tell the user if the task needs another site.\n"
         if browser_enabled else ""
     )
-    connector_rule = (
-        # Surgical tool pinning: these exact tool names are already ACTIVE (not
-        # deferred) — telling the model to search_tools/activate_tool them first
-        # would be a wasted round-trip against a tool that's already callable.
-        (
-            "- These tools are loaded and directly callable: " + ", ".join(pinned_tool_names) + ". "
-            "Call them directly; do NOT call search_tools/activate_tool for any of them.\n"
-            "- Aggregations (top-N, group-by, totals, a chart) usually have NO dedicated tool: "
-            "call the connector's GENERIC list/query tool, read the rows, and compute the "
-            "aggregation yourself. Never invent data - read it from the connector.\n"
-        )
-        if pinned_tool_names else
-        (
-            "- ACTIVE CONNECTORS for this turn: " + ", ".join(connector_services) + ". "
-            "These are the ONLY external systems available RIGHT NOW. This overrides the "
-            "conversation history: if earlier in this chat you used a DIFFERENT connector "
-            "(another ERP/app the user has since DESELECTED), it is NO LONGER available - do "
-            "NOT search for or call its tools, and do NOT reuse tool names or API verbs from "
-            "that system (e.g. do not look for another ERP's model/method names here).\n"
-            "- Their tools are not all loaded upfront: call search_tools(query=...) with PLAIN "
-            "BUSINESS keywords (\"sales orders\", \"customers\", \"unpaid invoices\", \"headcount\") "
-            "- never another system's internal API names - then activate_tool(name=...) ONCE, then "
-            "call it. The results ARE the available tools: pick the closest match and USE it; do "
-            "NOT keep re-searching for a tool from a different system. If two searches for the same "
-            "need return the same kind of tool, STOP and activate it.\n"
-            "- Aggregations (top-N, group-by, totals, a chart) usually have NO dedicated tool: "
-            "activate the connector's GENERIC list/query tool, read the rows, and compute the "
-            "aggregation yourself. Never invent data - read it from the connector.\n"
-            if connector_services else ""
-        )
-    )
+    # Surgical tool pinning: those exact tool names are already ACTIVE (not
+    # deferred), so the rule says to call them directly. Per-turn connectors
+    # (protocol 3): connector_services is empty here and the rule is rendered per
+    # turn instead (_live_connector_block, from the turn's selection).
+    connector_rule = _connector_rule(connector_services, pinned_tool_names)
     # Core primitives are ALWAYS in the lazy pool now, so the model must be told
     # they exist (they are not pinned/loaded upfront) — otherwise it concludes "no
     # web-search tool is available" and refuses, exactly the reported failure.
@@ -1011,7 +1270,7 @@ def _build_agent():
         # wall-clock budget is enforced separately in _run_turn.
         max_iters=(int(os.environ.get("MEL_ASSISTANT_MAX_ITERS_PHONE", "300") or "300") if phone_enabled
                    else (int(os.environ.get("MEL_ASSISTANT_MAX_ITERS_BROWSER", "300") or "300") if browser_enabled
-                         else (40 if connector_services else 8))),
+                         else (40 if (connector_services or _turn_connectors_mode()) else 8))),
         # EVERY assistant turn is long-horizon, not only device-driving ones.
         #
         # The codex cap is a latency default written for pipeline phases. An
@@ -1289,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
 
@@ -1296,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
 
@@ -1306,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
 
@@ -1319,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")
 
 
@@ -1344,6 +1607,14 @@ def _stdin_reader(q: "queue.Queue[str]") -> None:
                     if not tid or tid == _stream.get("turnId"):
                         _stream["cancel"] = True
                     continue  # consumed — do not queue as a turn
+                # Live mid-turn update (autonomy mode / connectors): applied HERE,
+                # while the turn runs, like STOP. Never queued as a turn.
+                if isinstance(req, dict) and req.get("kind") == "turn_update":
+                    try:
+                        _apply_turn_update(req)
+                    except Exception as exc:
+                        _log(f"turn_update failed: {type(exc).__name__}")
+                    continue
             q.put(line)
     except Exception:
         pass
@@ -1382,6 +1653,17 @@ def main() -> int:
     # Capture the freshly-built BASE system prompt (before any static context is
     # folded in) so each turn can deterministically rebuild base + persona.
     base_sys_prompt = getattr(agent, "_sys_prompt", "") or ""
+    _LIVE["agent"] = agent
+    _LIVE["basePrompt"] = base_sys_prompt
+    # Mid-turn connector activation (melaya_agent_request_connector_enable on a
+    # surface that turns connectors on by itself): the tool hands the server's
+    # categories + env to this host through shared.runtime.assistant_live.
+    if _turn_connectors_mode():
+        try:
+            from shared.runtime.assistant_live import register_connector_applier
+            register_connector_applier(_apply_live_connector_activation)
+        except Exception:
+            _log("assistant_live unavailable (older shared bundle): no mid-turn connector activation")
 
     # PR4: report memory watermark + host identity + generation so the server can
     # decide whether to offer a generation-bound rehydrate snapshot.
@@ -1498,11 +1780,18 @@ def main() -> int:
         # AgentScope spans are created; _emit_usage force-flushes them before the
         # next turn can replace the value.
         _apply_telemetry_surface(req.get("telemetry_surface"))
+        # Per-turn connectors (protocol 3): the frame carries the chat's selection
+        # + its env; apply both BEFORE the prompt is rendered (the connector rule
+        # is part of it). Absent (older server) => keep the boot-time scope.
+        if _turn_connectors_mode() and isinstance(req.get("connectors"), list):
+            _apply_turn_connectors(req.get("connectors"), req.get("connector_env") or {})
+        _LIVE["staticContext"] = req.get("static_context")
         # Per-turn STATIC CONTEXT: fold the conversation's persona / standing
         # instructions into the system prompt before running the turn (parity with
         # the cloud path; handles set / edit / clear mid-conversation).
         _apply_static_context(agent, base_sys_prompt, req.get("static_context"))
         if not message and not images:
+            _purge_connector_env()
             _emit(turn_id, "done")
             continue
         # P2-6: nudge the live memory budget down if a prior turn's OOM downgraded
@@ -1513,10 +1802,17 @@ 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.
+            if _turn_connectors_mode():
+                _purge_connector_env()
         _emit_usage(agent, turn_id)
 
 

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) => {