@melaya/runner 1.1.38 → 1.1.41

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]
 
@@ -512,9 +523,26 @@ def _extract_text(result) -> str:
 def _build_agent():
     """Build the single long-lived ReActAgent for this session."""
     from shared.runtime.agent_factory import make_agent
+    try:
+        from shared.orchestration.delegation import make_delegating_agent, DelegateSpec
+        _HAS_DELEGATION = True
+    except Exception:
+        # A runner on the NEW assistantHost.py against a STALE shared bundle that
+        # predates delegation.py must NOT brick — degrade to the plain agent
+        # build (delegates ignored, model_provider mapped back to provider=).
+        _HAS_DELEGATION = False
+        DelegateSpec = None  # sentinel; only referenced when _HAS_DELEGATION is True
+
+        def make_delegating_agent(*, model_provider="", delegates=None, **_kw):  # type: ignore[misc]
+            return make_agent(provider=model_provider, **_kw)
     from shared.runtime.registry import build_toolkit
 
     provider = os.environ.get("MEL_ASSISTANT_PROVIDER", "claude_code")
+    # Weak local models orchestrate sub-agents poorly — gate delegation OFF for
+    # them (mirrors the cloud SUBAGENT_INCAPABLE_PROVIDERS). When off, delegates
+    # is None and make_delegating_agent is byte-identical to the old make_agent
+    # build (no delegate_task tool, no prompt note).
+    _delegate_capable = _HAS_DELEGATION and provider.strip().lower() not in ("ollama", "lmstudio")
     model = os.environ.get("MEL_ASSISTANT_MODEL", "") or None
     language = os.environ.get("MEL_ASSISTANT_LANGUAGE", "en")
 
@@ -547,6 +575,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).
@@ -587,10 +622,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")
@@ -689,22 +731,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
@@ -736,9 +791,22 @@ def _build_agent():
         "- CHARTS: when you use the `chart` tool, the graph ONLY renders if you paste the EXACT ```chart ...``` fenced block it returns into your reply. ALWAYS output that block verbatim where you want the chart shown; NEVER say 'the chart is above/below' or describe it instead. If you made several charts, include each block; if you regenerated one, include ONLY the final good version.\n"
         "- If a question is outside the platform, answer normally without tools.\n"
         + (f"- Answer in the user's language: {language}.\n" if language and language != "en" else "")
+        # Provider-agnostic sub-agent delegation. The delegate_task tool is
+        # registered by make_delegating_agent below (only when _delegate_capable);
+        # tell the model it exists and how to use it well. Sub-agents share this
+        # same toolkit (writes hit the SAME HITL gate) and cannot delegate further.
+        # Gated on _delegate_capable so a weak-model turn's prompt is unchanged.
+        + ((
+            "- You MAY call delegate_task(\"Specialist\", \"<scoped sub-task>\") to hand a "
+            "self-contained sub-analysis to a specialist sub-agent. Use it to fan out "
+            "INDEPENDENT sub-tasks (they can run in parallel and, when useful, on a "
+            "different model), then SYNTHESISE the results yourself. Do not over-delegate, "
+            "never delegate the whole request, and remember sub-agents cannot delegate "
+            "further.\n"
+        ) if _delegate_capable else "")
     )
 
-    agent = make_agent(
+    agent = make_delegating_agent(
         # This name IS the agent identity that agentscope stamps onto the traced
         # `invoke_agent <name>` span + gen_ai.agent.name — which is EXACTLY the
         # dimension the Overview "by agent" token breakdown groups on
@@ -749,7 +817,28 @@ def _build_agent():
         sys_prompt=sys_prompt,
         toolkit=toolkit,
         model_name=model,
-        provider=provider,
+        # make_delegating_agent forwards model_provider both to make_agent (as the
+        # provider alias -> identical resolution to the old provider=) AND to the
+        # delegate factory, so a specialist defaults to the SAME provider as the
+        # lead. Pass provider here as model_provider (not provider=) so the sub-
+        # agent inherits it instead of falling back to the anthropic env default.
+        model_provider=provider,
+        # Provider-agnostic sub-agent delegation (UNCONDITIONAL — always on). The
+        # ONLY behavioural change vs the previous make_agent build is that the
+        # agent now also carries a delegate_task tool; every other kwarg below is
+        # unchanged. The Specialist shares THIS toolkit (HITL gating preserved),
+        # is built via make_agent (no delegate_task -> depth capped at 1), and can
+        # be run on a different model via MEL_ASSISTANT_DELEGATE_MODEL/PROVIDER.
+        delegates=([
+            DelegateSpec(
+                name="Specialist",
+                crew="assistant_delegate",
+                factory="make_assistant_specialist",
+                model_name=os.environ.get("MEL_ASSISTANT_DELEGATE_MODEL", "") or "",
+                model_provider=os.environ.get("MEL_ASSISTANT_DELEGATE_PROVIDER", "") or "",
+                max_iters=6,
+            ),
+        ] if _delegate_capable else None),
         # Cloud providers on the runner path (browser control turns pinned to the
         # runner even for a cloud model) get their key passed down from the server
         # as MEL_ASSISTANT_PROVIDER_API_KEY. Empty for local providers (claude_code
@@ -835,6 +924,14 @@ def _register_stream_hooks(agent) -> None:
     # the post-hook's trailing `output` arg so ONE shape works for both.
     def _pre_print_hook(_self, kw, *_rest) -> None:
         try:
+            # Sub-agents (Specialist) share this CLASS hook, but only the LEAD
+            # ("Assistant") streams to the client. A delegate's deltas / tool
+            # chips must NOT leak into the lead's answer bubble — its result comes
+            # back via the delegate_task tool result. (Specialist name is
+            # "Assistant:Specialist", so an exact-match on the lead name filters
+            # every sub-agent.)
+            if getattr(_self, "name", "") != "Assistant":
+                return
             tid = _stream.get("turnId")
             if not tid or not isinstance(kw, dict):
                 return
@@ -873,6 +970,10 @@ def _register_stream_hooks(agent) -> None:
 
     def _post_acting_hook(_self, kw, *_rest) -> None:
         try:
+            # Only the LEAD streams tool chips; a delegate's tool calls must not
+            # surface in the lead's turn (see _pre_print_hook).
+            if getattr(_self, "name", "") != "Assistant":
+                return
             tid = _stream.get("turnId")
             if not tid or not isinstance(kw, dict):
                 return
@@ -955,6 +1056,15 @@ def _run_turn(agent, turn_id: str, message: str, browser_turn: bool = False, ima
     _stream["cancel"] = False  # fresh turn — clear any stale STOP
     _stream["usedBrowser"] = False
 
+    # Reset the per-turn sub-agent delegation budget so the breadth cap is per
+    # turn, not per session. Best-effort: never let a stale/absent bundle break a
+    # turn (recursion is still capped structurally regardless of this reset).
+    try:
+        from crews.assistant_delegate.main import reset_delegation_budget
+        reset_delegation_budget()
+    except Exception:
+        pass
+
     # Browser turns carry a WALL-CLOCK budget on top of the round budget
     # (plan 0.3): the per-turn grant is short-lived and a wedged page must not
     # pin the host. Cancellation uses the same task.cancel() path as STOP.

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.38",
+  "version": "1.1.41",
   "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"
   },