@melaya/runner 1.1.37 → 1.1.40

package/dist/assistantHost.py

@@ -159,6 +159,17 @@ def _config_hash() -> str:
     ]
     if _browser_capable():
         fields.append("browser")
+    # Surgical tool pinning: PRESENCE of pinned tool names is part of the host
+    # boot config, exactly like browser capability above — a warm host that
+    # never registered a pinned tool active must reboot when a turn first
+    # requests one. Byte-for-byte identical to runnerNamespace.ts
+    # _assistantConfigHash: lowercased+sorted+joined, appended ONLY when
+    # non-empty so a turn with no pinned tools hashes exactly like a
+    # pre-pinning build (parity preserved).
+    raw_pinned = os.environ.get("MEL_ASSISTANT_PINNED_TOOLS", "") or ""
+    pinned_tools = ",".join(sorted(t.lower() for t in raw_pinned.split(",") if t.strip()))
+    if pinned_tools:
+        fields.append(pinned_tools)
     canon = "|".join(fields)
     return hashlib.sha256(canon.encode("utf-8")).hexdigest()[:32]
 
@@ -184,7 +195,16 @@ def _render_summary_text(summary) -> str:
 # Streaming state for the CURRENT turn — the pre_print / post_acting hooks read
 # this to emit delta / tool events keyed to the turn in flight. `cancel` is the
 # STOP flag: set by the stdin-reader thread, polled by the running turn.
-_stream = {"turnId": "", "lens": {}, "cancel": False, "usedBrowser": False}
+_stream = {"turnId": "", "lens": {}, "cancel": False, "usedBrowser": False,
+           "deltaBuf": "", "deltaMid": ""}
+
+# Coalesce per-token pre_print fragments before emitting a `delta`. agentscope
+# hands us one cumulative snapshot per model chunk; a streaming Anthropic/OpenAI
+# response fragments the answer into 2-15 char pieces, and emitting a MELASSIST
+# line (→ socket → server → SSE → client) PER fragment made streaming read as
+# ultra-choppy / ultra-slow (hundreds of round-trips for one answer). Hold the
+# suffix until it reaches ~a clause or hits a line break, then flush one delta.
+_DELTA_FLUSH_CHARS = 48
 
 # Sentinel returned by a turn's coroutine when the user pressed STOP.
 _CANCELLED = object()
@@ -417,6 +437,18 @@ def _emit(turn_id: str, kind: str, **fields) -> None:
         pass
 
 
+def _flush_delta(turn_id: str) -> None:
+    """Emit any buffered pre_print suffix as one `delta` and clear the buffer.
+
+    Called from the pre_print hook when the buffer fills / a message boundary is
+    crossed, and from _run_turn just before the authoritative `text` swap so the
+    last partial clause is not left un-streamed."""
+    buf = _stream.get("deltaBuf") or ""
+    if buf and turn_id:
+        _emit(turn_id, "delta", content=buf)
+    _stream["deltaBuf"] = ""
+
+
 def _log(msg: str) -> None:
     # Diagnostics go to stderr (the runner logs stderr; stdout is the event channel).
     try:
@@ -526,6 +558,13 @@ def _build_agent():
     # explodes context. Bounded to the selected services so the model can't reach
     # a connector the user didn't enable / has no creds for.
     connector_services = [s.strip().lower() for s in os.environ.get("MEL_ASSISTANT_CONNECTORS", "").split(",") if s.strip()]
+    # Surgical tool pinning (Melaya Marketing): exact connector tool NAMES the
+    # server already resolved creds for (e.g. gsc_search_analytics,
+    # gads_update_budget) — passed straight through, no lowercasing, since tool
+    # names are case-sensitive Python identifiers (unlike connector_services,
+    # which are lowercased service ids). Registered ACTIVE at boot below so the
+    # model calls them directly instead of search_tools/activate_tool.
+    pinned_tool_names = [t.strip() for t in os.environ.get("MEL_ASSISTANT_PINNED_TOOLS", "").split(",") if t.strip()]
     # Self-arm the write-approval gate whenever connectors are active, so it can't
     # be silently OFF on an older runner build that didn't set this env. Writes
     # then ALWAYS require the in-chat approval card (fail-safe).
@@ -566,10 +605,17 @@ def _build_agent():
         # management + every browser action is directly callable, no search/activate.
         if browser_enabled:
             _budget = max(_budget, 64)
+        # Surgical tool pinning: widen the budget so every pinned tool fits
+        # alongside the base active set (melaya_agent + phone/browser if
+        # enabled) — mirrors the phone_enabled/browser_enabled widening above,
+        # 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(
             active_categories=categories,
             include_categories=categories + core_categories + connector_services,
             budget=_budget,
+            pinned_names=pinned_tool_names or None,
         )
     except Exception as exc:
         _log(f"toolkit build failed (connectors={connector_services}, core): {exc}; retrying melaya_agent only")
@@ -668,22 +714,35 @@ def _build_agent():
         if browser_enabled else ""
     )
     connector_rule = (
-        "- 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: 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 ""
+        )
     )
     # 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
@@ -826,19 +885,27 @@ def _register_stream_hooks(agent) -> None:
                 return
             prev = _stream["lens"].get(mid, 0)
             if len(text) > prev:
-                # ReAct emits one message PER iteration: the running chain-of-thought
-                # ("Let me...", "Actually...", the plan before each tool call). That
-                # is REASONING, not the answer. Streaming it as `delta` dumped every
-                # round's raw thought into the chat bubble with no separator between
-                # rounds ("...page content.I notice..."), which read as broken run-on
-                # sentences. Route it to `think` instead (the ephemeral thinking
-                # strip) so it MIRRORS the cloud provider mapping (thinking_delta ->
-                # think, answer -> text). The clean authoritative answer still lands
-                # in the bubble via the end-of-turn `text` event (_run_turn), so the
-                # message reads like one professional reply, reasoning stays in its
-                # own channel, and tool chips show the live steps.
-                _emit(tid, "think", content=text[prev:])
+                # ReAct emits one message PER iteration. We stream every message's
+                # growing suffix into the answer bubble as `delta` so the reply
+                # TYPES OUT live (this is the same channel cloud providers stream
+                # on) instead of only landing whole at end-of-turn. The end-of-turn
+                # `text` event (_run_turn) still swaps in the clean, authoritative
+                # markdown answer, so transient tool preambles that streamed here
+                # get replaced by the final professional reply. A blank line
+                # separates successive ReAct messages so rounds don't run together
+                # ("...page content.I notice..."). Fragments are coalesced (see
+                # _DELTA_FLUSH_CHARS) so we emit clause-sized deltas, not one
+                # socket round-trip per token.
+                suffix = text[prev:]
                 _stream["lens"][mid] = len(text)
+                if mid != _stream.get("deltaMid"):
+                    _flush_delta(tid)  # flush the previous message's tail
+                    if _stream.get("deltaMid"):
+                        _stream["deltaBuf"] = "\n\n"
+                    _stream["deltaMid"] = mid
+                _stream["deltaBuf"] = _stream.get("deltaBuf", "") + suffix
+                if len(_stream["deltaBuf"]) >= _DELTA_FLUSH_CHARS or "\n" in suffix:
+                    _flush_delta(tid)
         except Exception:
             pass
 
@@ -921,6 +988,8 @@ def _run_turn(agent, turn_id: str, message: str, browser_turn: bool = False, ima
     _emit(turn_id, "round", n=1)
     _stream["turnId"] = turn_id
     _stream["lens"] = {}
+    _stream["deltaBuf"] = ""   # fresh turn — drop any stale streamed suffix
+    _stream["deltaMid"] = ""
     _stream["cancel"] = False  # fresh turn — clear any stale STOP
     _stream["usedBrowser"] = False
 
@@ -993,6 +1062,7 @@ def _run_turn(agent, turn_id: str, message: str, browser_turn: bool = False, ima
         _emit(turn_id, "done")
         return
 
+    _flush_delta(turn_id)  # push the last buffered clause before the swap
     _stream["turnId"] = ""
     # Authoritative final answer — the client swaps the streamed plain text for
     # this markdown-rendered version.

package/dist/connection.js

@@ -1374,6 +1374,12 @@ export async function connect(opts) {
                 // 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(",") : "",
+                // 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
+                // search_tools -> activate_tool round-trip for known marketing tools.
+                // 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" : "",
                 // HITL autonomy mode ("safe" | "autonomous" | "payments_only"). The host
@@ -2198,6 +2204,108 @@ export async function connect(opts) {
             });
         }
     });
+    // ── DB "Test connection via runner" ───────────────────────────────
+    // The server hands us DB credentials (over the authenticated socket) so we can
+    // probe a database that only THIS machine can reach — IP-allow-listed or in a
+    // VPC the cloud can't see. We open one read-only connection and report back.
+    // Credentials arrive via stdin (never argv, never disk) and are not persisted.
+    socket.on("runner:db-test", async (payload, ack) => {
+        const sid = payload?.sessionId;
+        if (!sid)
+            return;
+        ack?.({ ok: true });
+        const reply = (ok, message, error) => socket.emit("runner:db-test-result", { session_id: sid, ok, message, error });
+        try {
+            const { ensurePythonEnv } = await import("./pythonEnv.js");
+            const { getLocalSharedVersion } = await import("./sharedVendor.js");
+            // Reuse the venv already on disk — pass the ACTUAL installed shared version
+            // (the venv marker is an exact match on `${version}::${depsHash}`, so a
+            // sentinel like "latest" would force a needless full rebuild). If the
+            // bundle isn't present yet, bail with a clear message rather than build.
+            const localVersion = getLocalSharedVersion();
+            if (!localVersion) {
+                reply(false, undefined, "runner is still setting up its Python runtime — try again in a moment");
+                return;
+            }
+            const env = await ensurePythonEnv(opts.pythonPath, localVersion, (m) => { if (opts.verbose)
+                console.log(chalk.gray(`  [db-test venv] ${m}`)); });
+            if (!env.ok) {
+                reply(false, undefined, `venv bootstrap failed: ${env.reason}`);
+                return;
+            }
+            const { existsSync, copyFileSync, mkdirSync } = await import("fs");
+            const workDir = join(tmpdir(), `melaya-db-test-${Date.now()}`);
+            mkdirSync(workDir, { recursive: true });
+            const candidates = [
+                join(__dirname, "localDbProbe.py"),
+                join(__dirname, "..", "localDbProbe.py"),
+            ];
+            let found = "";
+            for (const c of candidates) {
+                if (existsSync(c)) {
+                    found = c;
+                    break;
+                }
+            }
+            if (!found) {
+                reply(false, undefined, "localDbProbe.py not found — update @melaya/runner");
+                return;
+            }
+            const staged = join(workDir, "localDbProbe.py");
+            copyFileSync(found, staged);
+            const certBundle = (await import("./pythonEnv.js")).getCertBundlePath();
+            const sslEnv = certBundle
+                ? { SSL_CERT_FILE: certBundle, REQUESTS_CA_BUNDLE: certBundle } : {};
+            const proc = spawn(env.pythonPath, ["-u", staged], {
+                env: { ...process.env, ...sslEnv },
+                cwd: workDir,
+            });
+            let stdout = "";
+            let stderr = "";
+            let done = false;
+            const finish = (ok, message, error) => {
+                if (done)
+                    return;
+                done = true;
+                reply(ok, message, error);
+            };
+            // Hard wall-clock cap so a hung TCP connect can't wedge the session.
+            const killTimer = setTimeout(() => {
+                try {
+                    proc.kill();
+                }
+                catch { /* already gone */ }
+                finish(false, undefined, "probe timed out after 30s (host unreachable from the runner?)");
+            }, 30_000);
+            proc.stdout.on("data", (d) => { stdout += d.toString("utf-8"); });
+            proc.stderr.on("data", (d) => { stderr += d.toString("utf-8"); });
+            proc.on("error", (err) => { clearTimeout(killTimer); finish(false, undefined, err?.message || String(err)); });
+            proc.on("close", (code) => {
+                clearTimeout(killTimer);
+                const jsonLine = stdout.split(/\r?\n/).map(s => s.trim()).filter(Boolean).reverse()[0] || "";
+                let parsed = null;
+                try {
+                    parsed = JSON.parse(jsonLine);
+                }
+                catch { /* handled below */ }
+                if (parsed && typeof parsed.ok === "boolean") {
+                    finish(parsed.ok, parsed.message, parsed.error);
+                }
+                else {
+                    finish(false, undefined, `probe exited ${code ?? "?"}${stderr ? `: ${stderr.slice(-300)}` : ""}`);
+                }
+            });
+            // Hand the credentials to the probe over stdin — never argv/disk.
+            try {
+                proc.stdin.write(JSON.stringify({ service: payload.service, creds: payload.creds || {} }));
+                proc.stdin.end();
+            }
+            catch { /* proc.on('error') handles it */ }
+        }
+        catch (e) {
+            reply(false, undefined, e?.message || String(e));
+        }
+    });
     socket.on("linkedin:start-login", async (req) => {
         const sid = req?.session_id;
         if (!sid)

package/dist/localDbProbe.py

@@ -0,0 +1,252 @@
+#!/usr/bin/env python3
+"""
+localDbProbe.py — one-shot, read-only database reachability probe run BY THE
+RUNNER on behalf of the Melaya server.
+
+Why it exists: some databases sit behind an IP allow-list or inside a VPC that
+the Melaya cloud can never reach, but the user's own runner (on their LAN /
+bastion) can. The server hands us the resolved credentials over the already-
+authenticated Socket.IO channel; we open a single real connection from THIS
+machine's network vantage point, run a trivial read-only probe, and print the
+outcome. We never persist the credentials and never write to the database.
+
+Contract:
+  stdin  : one JSON object {"service": "...", "creds": { ... }}
+  stdout : one JSON object {"ok": bool, "message"|"error": "..."}
+Exit code is always 0 (the result is the JSON on stdout); any crash is caught
+and reported as {"ok": false, "error": ...}.
+"""
+import sys
+import json
+import base64
+import hashlib
+import urllib.parse
+
+
+def _out(ok, text):
+    key = "message" if ok else "error"
+    sys.stdout.write(json.dumps({"ok": bool(ok), key: str(text)[:300]}))
+    sys.stdout.flush()
+    sys.exit(0)
+
+
+def _pick(creds, *keys):
+    for k in keys:
+        v = (creds.get(k) or "").strip()
+        if v:
+            return v
+    return ""
+
+
+# ── PostgreSQL (asyncpg) ─────────────────────────────────────────────────────
+def probe_postgres(creds):
+    dsn = _pick(creds, "dsn", "POSTGRES_DSN")
+    if not dsn:
+        _out(False, "Connection DSN required")
+    try:
+        import asyncio
+        import asyncpg  # type: ignore
+    except ImportError:
+        _out(False, "asyncpg not installed on this runner (pip install asyncpg)")
+
+    async def _run():
+        conn = await asyncpg.connect(dsn, timeout=10)
+        try:
+            await conn.fetchval("SELECT 1")
+            ver = await conn.fetchval("SELECT version()")
+        finally:
+            await conn.close()
+        return ver or ""
+
+    try:
+        ver = asyncio.run(asyncio.wait_for(_run(), timeout=15))
+        short = str(ver).split(" on ")[0] if ver else ""
+        _out(True, f"Connected to PostgreSQL{(' — ' + short) if short else ''}")
+    except Exception as e:  # noqa: BLE001
+        _out(False, f"PostgreSQL connection failed: {e}")
+
+
+# ── MySQL / MariaDB (PyMySQL — pure-python, sync) ────────────────────────────
+def probe_mysql(creds):
+    dsn = _pick(creds, "dsn", "MYSQL_DSN")
+    if not dsn:
+        _out(False, "Connection DSN required")
+    try:
+        import pymysql  # type: ignore
+    except ImportError:
+        _out(False, "PyMySQL not installed on this runner (pip install PyMySQL)")
+    try:
+        p = urllib.parse.urlparse(dsn)
+        conn = pymysql.connect(
+            host=p.hostname,
+            port=p.port or 3306,
+            user=urllib.parse.unquote(p.username or ""),
+            password=urllib.parse.unquote(p.password or ""),
+            db=(p.path or "").lstrip("/") or None,
+            connect_timeout=10,
+            read_timeout=10,
+        )
+        try:
+            with conn.cursor() as cur:
+                cur.execute("SELECT VERSION()")
+                row = cur.fetchone()
+            ver = (row[0] if row else "") or ""
+        finally:
+            conn.close()
+        _out(True, f"Connected to MySQL{(' — ' + str(ver)) if ver else ''}")
+    except Exception as e:  # noqa: BLE001
+        _out(False, f"MySQL connection failed: {e}")
+
+
+# ── Snowflake (key-pair JWT, mirrors the server handler) ─────────────────────
+def probe_snowflake(creds):
+    account = _pick(creds, "account", "SNOWFLAKE_ACCOUNT")
+    user = _pick(creds, "user", "SNOWFLAKE_USER")
+    pk = _pick(creds, "private_key", "SNOWFLAKE_PRIVATE_KEY")
+    if not account or not user or not pk:
+        _out(False, "Account + Username + Private Key required")
+    try:
+        from cryptography.hazmat.primitives import serialization  # type: ignore
+        import requests  # type: ignore
+    except ImportError:
+        _out(False, "cryptography/requests not installed on this runner")
+
+    def b64url(b):
+        if isinstance(b, str):
+            b = b.encode()
+        return base64.urlsafe_b64encode(b).rstrip(b"=").decode()
+
+    try:
+        import time
+        key = serialization.load_pem_private_key(pk.encode(), password=None)
+        der_spki = key.public_key().public_bytes(
+            serialization.Encoding.DER,
+            serialization.PublicFormat.SubjectPublicKeyInfo,
+        )
+        fp = "SHA256:" + base64.b64encode(hashlib.sha256(der_spki).digest()).decode()
+        acct_upper = account.upper()
+        if "." in acct_upper:
+            acct_upper = acct_upper.split(".")[0]
+        qual = f"{acct_upper}.{user.upper()}"
+        now = int(time.time())
+        header = b64url(json.dumps({"alg": "RS256", "typ": "JWT"}))
+        payload = b64url(json.dumps(
+            {"iss": f"{qual}.{fp}", "sub": qual, "iat": now, "exp": now + 3540}))
+        signing_input = f"{header}.{payload}".encode()
+        from cryptography.hazmat.primitives import hashes  # type: ignore
+        from cryptography.hazmat.primitives.asymmetric import padding  # type: ignore
+        sig = key.sign(signing_input, padding.PKCS1v15(), hashes.SHA256())
+        jwt = f"{header}.{payload}.{b64url(sig)}"
+        host = f"https://{account.replace('_', '-').lower()}.snowflakecomputing.com"
+        r = requests.post(
+            f"{host}/api/v2/statements",
+            headers={
+                "Authorization": f"Bearer {jwt}",
+                "X-Snowflake-Authorization-Token-Type": "KEYPAIR_JWT",
+                "Content-Type": "application/json",
+                "Accept": "application/json",
+            },
+            json={"statement": "SELECT CURRENT_VERSION()", "timeout": 20},
+            timeout=15,
+        )
+        if r.ok:
+            v = ""
+            try:
+                v = (r.json().get("data") or [[None]])[0][0] or ""
+            except Exception:  # noqa: BLE001
+                pass
+            _out(True, f"Connected to Snowflake{(' (v' + str(v) + ')') if v else ''}")
+        _out(False, f"Snowflake auth/query failed: HTTP {r.status_code} {r.text[:160]}")
+    except Exception as e:  # noqa: BLE001
+        _out(False, f"Snowflake connection failed: {e}")
+
+
+# ── Databricks (PAT or OAuth M2M, mirrors the server handler) ────────────────
+def probe_databricks(creds):
+    host = _pick(creds, "workspace_url", "DATABRICKS_HOST").rstrip("/")
+    pat = _pick(creds, "token", "DATABRICKS_TOKEN")
+    cid = _pick(creds, "client_id", "DATABRICKS_CLIENT_ID")
+    sec = _pick(creds, "client_secret", "DATABRICKS_CLIENT_SECRET")
+    if not host:
+        _out(False, "Workspace URL required")
+    try:
+        import requests  # type: ignore
+    except ImportError:
+        _out(False, "requests not installed on this runner")
+    try:
+        bearer = pat
+        if not bearer:
+            if not cid or not sec:
+                _out(False, "Provide a Personal Access Token, or Client ID + Client Secret")
+            tr = requests.post(
+                f"{host}/oidc/v1/token",
+                auth=(cid, sec),
+                data={"grant_type": "client_credentials", "scope": "all-apis"},
+                timeout=12,
+            )
+            tj = {}
+            try:
+                tj = tr.json()
+            except Exception:  # noqa: BLE001
+                pass
+            if not tr.ok or not tj.get("access_token"):
+                _out(False, f"Databricks OAuth failed: {tj.get('error_description') or tj.get('error') or ('HTTP ' + str(tr.status_code))}")
+            bearer = tj["access_token"]
+        r = requests.get(
+            f"{host}/api/2.1/clusters/list?page_size=1",
+            headers={"Authorization": f"Bearer {bearer}"},
+            timeout=12,
+        )
+        if r.ok:
+            _out(True, f"Connected to Databricks ({host.replace('https://', '').replace('http://', '')})")
+        _out(False, f"Databricks unreachable: HTTP {r.status_code} {r.text[:120]}")
+    except Exception as e:  # noqa: BLE001
+        _out(False, f"Databricks connection failed: {e}")
+
+
+# ── SQLite (local file on the runner) ────────────────────────────────────────
+def probe_sqlite(creds):
+    import os
+    import sqlite3
+    path = _pick(creds, "dsn", "db_path", "path")
+    if not path:
+        _out(False, "Database file path required")
+    if not os.path.exists(path):
+        _out(False, f"No SQLite file at {path}")
+    try:
+        conn = sqlite3.connect(path, timeout=8)
+        try:
+            conn.execute("SELECT 1")
+        finally:
+            conn.close()
+        _out(True, f"Opened SQLite database ({os.path.basename(path)})")
+    except Exception as e:  # noqa: BLE001
+        _out(False, f"SQLite open failed: {e}")
+
+
+_PROBES = {
+    "postgres": probe_postgres,
+    "mysql": probe_mysql,
+    "snowflake": probe_snowflake,
+    "databricks": probe_databricks,
+    "sqlite": probe_sqlite,
+}
+
+
+def main():
+    try:
+        job = json.loads(sys.stdin.read() or "{}")
+    except Exception as e:  # noqa: BLE001
+        _out(False, f"bad probe job: {e}")
+        return
+    service = (job.get("service") or "").strip()
+    creds = job.get("creds") or {}
+    fn = _PROBES.get(service)
+    if not fn:
+        _out(False, f"unsupported service: {service}")
+        return
+    fn(creds)
+
+
+if __name__ == "__main__":
+    main()

package/localDbProbe.py

@@ -0,0 +1,252 @@
+#!/usr/bin/env python3
+"""
+localDbProbe.py — one-shot, read-only database reachability probe run BY THE
+RUNNER on behalf of the Melaya server.
+
+Why it exists: some databases sit behind an IP allow-list or inside a VPC that
+the Melaya cloud can never reach, but the user's own runner (on their LAN /
+bastion) can. The server hands us the resolved credentials over the already-
+authenticated Socket.IO channel; we open a single real connection from THIS
+machine's network vantage point, run a trivial read-only probe, and print the
+outcome. We never persist the credentials and never write to the database.
+
+Contract:
+  stdin  : one JSON object {"service": "...", "creds": { ... }}
+  stdout : one JSON object {"ok": bool, "message"|"error": "..."}
+Exit code is always 0 (the result is the JSON on stdout); any crash is caught
+and reported as {"ok": false, "error": ...}.
+"""
+import sys
+import json
+import base64
+import hashlib
+import urllib.parse
+
+
+def _out(ok, text):
+    key = "message" if ok else "error"
+    sys.stdout.write(json.dumps({"ok": bool(ok), key: str(text)[:300]}))
+    sys.stdout.flush()
+    sys.exit(0)
+
+
+def _pick(creds, *keys):
+    for k in keys:
+        v = (creds.get(k) or "").strip()
+        if v:
+            return v
+    return ""
+
+
+# ── PostgreSQL (asyncpg) ─────────────────────────────────────────────────────
+def probe_postgres(creds):
+    dsn = _pick(creds, "dsn", "POSTGRES_DSN")
+    if not dsn:
+        _out(False, "Connection DSN required")
+    try:
+        import asyncio
+        import asyncpg  # type: ignore
+    except ImportError:
+        _out(False, "asyncpg not installed on this runner (pip install asyncpg)")
+
+    async def _run():
+        conn = await asyncpg.connect(dsn, timeout=10)
+        try:
+            await conn.fetchval("SELECT 1")
+            ver = await conn.fetchval("SELECT version()")
+        finally:
+            await conn.close()
+        return ver or ""
+
+    try:
+        ver = asyncio.run(asyncio.wait_for(_run(), timeout=15))
+        short = str(ver).split(" on ")[0] if ver else ""
+        _out(True, f"Connected to PostgreSQL{(' — ' + short) if short else ''}")
+    except Exception as e:  # noqa: BLE001
+        _out(False, f"PostgreSQL connection failed: {e}")
+
+
+# ── MySQL / MariaDB (PyMySQL — pure-python, sync) ────────────────────────────
+def probe_mysql(creds):
+    dsn = _pick(creds, "dsn", "MYSQL_DSN")
+    if not dsn:
+        _out(False, "Connection DSN required")
+    try:
+        import pymysql  # type: ignore
+    except ImportError:
+        _out(False, "PyMySQL not installed on this runner (pip install PyMySQL)")
+    try:
+        p = urllib.parse.urlparse(dsn)
+        conn = pymysql.connect(
+            host=p.hostname,
+            port=p.port or 3306,
+            user=urllib.parse.unquote(p.username or ""),
+            password=urllib.parse.unquote(p.password or ""),
+            db=(p.path or "").lstrip("/") or None,
+            connect_timeout=10,
+            read_timeout=10,
+        )
+        try:
+            with conn.cursor() as cur:
+                cur.execute("SELECT VERSION()")
+                row = cur.fetchone()
+            ver = (row[0] if row else "") or ""
+        finally:
+            conn.close()
+        _out(True, f"Connected to MySQL{(' — ' + str(ver)) if ver else ''}")
+    except Exception as e:  # noqa: BLE001
+        _out(False, f"MySQL connection failed: {e}")
+
+
+# ── Snowflake (key-pair JWT, mirrors the server handler) ─────────────────────
+def probe_snowflake(creds):
+    account = _pick(creds, "account", "SNOWFLAKE_ACCOUNT")
+    user = _pick(creds, "user", "SNOWFLAKE_USER")
+    pk = _pick(creds, "private_key", "SNOWFLAKE_PRIVATE_KEY")
+    if not account or not user or not pk:
+        _out(False, "Account + Username + Private Key required")
+    try:
+        from cryptography.hazmat.primitives import serialization  # type: ignore
+        import requests  # type: ignore
+    except ImportError:
+        _out(False, "cryptography/requests not installed on this runner")
+
+    def b64url(b):
+        if isinstance(b, str):
+            b = b.encode()
+        return base64.urlsafe_b64encode(b).rstrip(b"=").decode()
+
+    try:
+        import time
+        key = serialization.load_pem_private_key(pk.encode(), password=None)
+        der_spki = key.public_key().public_bytes(
+            serialization.Encoding.DER,
+            serialization.PublicFormat.SubjectPublicKeyInfo,
+        )
+        fp = "SHA256:" + base64.b64encode(hashlib.sha256(der_spki).digest()).decode()
+        acct_upper = account.upper()
+        if "." in acct_upper:
+            acct_upper = acct_upper.split(".")[0]
+        qual = f"{acct_upper}.{user.upper()}"
+        now = int(time.time())
+        header = b64url(json.dumps({"alg": "RS256", "typ": "JWT"}))
+        payload = b64url(json.dumps(
+            {"iss": f"{qual}.{fp}", "sub": qual, "iat": now, "exp": now + 3540}))
+        signing_input = f"{header}.{payload}".encode()
+        from cryptography.hazmat.primitives import hashes  # type: ignore
+        from cryptography.hazmat.primitives.asymmetric import padding  # type: ignore
+        sig = key.sign(signing_input, padding.PKCS1v15(), hashes.SHA256())
+        jwt = f"{header}.{payload}.{b64url(sig)}"
+        host = f"https://{account.replace('_', '-').lower()}.snowflakecomputing.com"
+        r = requests.post(
+            f"{host}/api/v2/statements",
+            headers={
+                "Authorization": f"Bearer {jwt}",
+                "X-Snowflake-Authorization-Token-Type": "KEYPAIR_JWT",
+                "Content-Type": "application/json",
+                "Accept": "application/json",
+            },
+            json={"statement": "SELECT CURRENT_VERSION()", "timeout": 20},
+            timeout=15,
+        )
+        if r.ok:
+            v = ""
+            try:
+                v = (r.json().get("data") or [[None]])[0][0] or ""
+            except Exception:  # noqa: BLE001
+                pass
+            _out(True, f"Connected to Snowflake{(' (v' + str(v) + ')') if v else ''}")
+        _out(False, f"Snowflake auth/query failed: HTTP {r.status_code} {r.text[:160]}")
+    except Exception as e:  # noqa: BLE001
+        _out(False, f"Snowflake connection failed: {e}")
+
+
+# ── Databricks (PAT or OAuth M2M, mirrors the server handler) ────────────────
+def probe_databricks(creds):
+    host = _pick(creds, "workspace_url", "DATABRICKS_HOST").rstrip("/")
+    pat = _pick(creds, "token", "DATABRICKS_TOKEN")
+    cid = _pick(creds, "client_id", "DATABRICKS_CLIENT_ID")
+    sec = _pick(creds, "client_secret", "DATABRICKS_CLIENT_SECRET")
+    if not host:
+        _out(False, "Workspace URL required")
+    try:
+        import requests  # type: ignore
+    except ImportError:
+        _out(False, "requests not installed on this runner")
+    try:
+        bearer = pat
+        if not bearer:
+            if not cid or not sec:
+                _out(False, "Provide a Personal Access Token, or Client ID + Client Secret")
+            tr = requests.post(
+                f"{host}/oidc/v1/token",
+                auth=(cid, sec),
+                data={"grant_type": "client_credentials", "scope": "all-apis"},
+                timeout=12,
+            )
+            tj = {}
+            try:
+                tj = tr.json()
+            except Exception:  # noqa: BLE001
+                pass
+            if not tr.ok or not tj.get("access_token"):
+                _out(False, f"Databricks OAuth failed: {tj.get('error_description') or tj.get('error') or ('HTTP ' + str(tr.status_code))}")
+            bearer = tj["access_token"]
+        r = requests.get(
+            f"{host}/api/2.1/clusters/list?page_size=1",
+            headers={"Authorization": f"Bearer {bearer}"},
+            timeout=12,
+        )
+        if r.ok:
+            _out(True, f"Connected to Databricks ({host.replace('https://', '').replace('http://', '')})")
+        _out(False, f"Databricks unreachable: HTTP {r.status_code} {r.text[:120]}")
+    except Exception as e:  # noqa: BLE001
+        _out(False, f"Databricks connection failed: {e}")
+
+
+# ── SQLite (local file on the runner) ────────────────────────────────────────
+def probe_sqlite(creds):
+    import os
+    import sqlite3
+    path = _pick(creds, "dsn", "db_path", "path")
+    if not path:
+        _out(False, "Database file path required")
+    if not os.path.exists(path):
+        _out(False, f"No SQLite file at {path}")
+    try:
+        conn = sqlite3.connect(path, timeout=8)
+        try:
+            conn.execute("SELECT 1")
+        finally:
+            conn.close()
+        _out(True, f"Opened SQLite database ({os.path.basename(path)})")
+    except Exception as e:  # noqa: BLE001
+        _out(False, f"SQLite open failed: {e}")
+
+
+_PROBES = {
+    "postgres": probe_postgres,
+    "mysql": probe_mysql,
+    "snowflake": probe_snowflake,
+    "databricks": probe_databricks,
+    "sqlite": probe_sqlite,
+}
+
+
+def main():
+    try:
+        job = json.loads(sys.stdin.read() or "{}")
+    except Exception as e:  # noqa: BLE001
+        _out(False, f"bad probe job: {e}")
+        return
+    service = (job.get("service") or "").strip()
+    creds = job.get("creds") or {}
+    fn = _PROBES.get(service)
+    if not fn:
+        _out(False, f"unsupported service: {service}")
+        return
+    fn(creds)
+
+
+if __name__ == "__main__":
+    main()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@melaya/runner",
-  "version": "1.1.37",
+  "version": "1.1.40",
   "description": "Run Melaya AI pipelines locally with your own LM Studio or Ollama models",
   "license": "UNLICENSED",
   "private": false,
@@ -15,11 +15,12 @@
     "dist/**/*.py",
     "localRagIngest.py",
     "localRagRetrieve.py",
+    "localDbProbe.py",
     "nltk_data/**",
     "README.md"
   ],
   "scripts": {
-    "build": "tsc && node -e \"const fs=require('fs'); fs.copyFileSync('localRagIngest.py','dist/localRagIngest.py'); fs.copyFileSync('localRagRetrieve.py','dist/localRagRetrieve.py'); fs.copyFileSync('src/assistantHost.py','dist/assistantHost.py')\"",
+    "build": "tsc && node -e \"const fs=require('fs'); fs.copyFileSync('localRagIngest.py','dist/localRagIngest.py'); fs.copyFileSync('localRagRetrieve.py','dist/localRagRetrieve.py'); fs.copyFileSync('localDbProbe.py','dist/localDbProbe.py'); fs.copyFileSync('src/assistantHost.py','dist/assistantHost.py')\"",
     "test": "node --test --import tsx \"src/**/*.test.ts\"",
     "prepublishOnly": "npm run build"
   },