feat(dispatch): wire JS cartridge dispatch via Deno + fix so_path derivation

BojRest.JsInvoker: forks `deno run priv/js_runner.js <mod_js_path> <tool>
<args_json>` per invocation (Phase 1 fork-per-call), 30s timeout via
Task.yield/shutdown, structured error classification.

elixir/priv/js_runner.js: thin Deno harness — dynamic-imports mod.js,
calls handleTool(toolName, args), writes {status, data} JSON to stdout.
Permissions: --allow-net --allow-env --allow-read.

Router.dispatch/3: branches on cart["ffi"] presence.
  - "ffi" key present  → BojRest.Invoker  (Zig .so via boj-invoke)
  - "ffi" key absent   → BojRest.JsInvoker (Deno mod.js)

cartridge_so_path/1: now reads cart["ffi"]["so_path"] from the manifest
instead of hardcoding the derivation. Removes name_to_lib/1 helper.

Verified: js_runner + model-router-mcp (pure local), local-memory-mcp
(correct 503 when backend absent), deno 2.6.10.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: hyperpolymath

elixir/lib/boj_rest/js_invoker.ex

@@ -0,0 +1,155 @@
+# SPDX-License-Identifier: PMPL-1.0-or-later
+# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+defmodule BojRest.JsInvoker do
+  @moduledoc """
+  Invokes a JS cartridge by shelling out to Deno with `priv/js_runner.js`.
+
+  Each call forks a fresh Deno process (Phase 1 — fork-per-call).  The ~200 ms
+  cold-start overhead is acceptable until there is enough traffic to justify a
+  persistent worker pool (Phase 2).
+
+  Dispatch path:
+    BojRest.Router
+      → BojRest.JsInvoker.invoke/3
+        → deno run priv/js_runner.js <mod_js_path> <tool_name> <args_json>
+          → cartridge/*/mod.js handleTool(toolName, args)
+          ← { status, data } JSON on stdout
+
+  Deno permissions granted per invocation:
+    --allow-net    cartridge fetch() calls to upstream backends
+    --allow-env    cartridge Deno.env.get() for API keys / URLs
+    --allow-read   dynamic import resolution of mod.js by the runner
+
+  Resolution order for the Deno binary:
+    1. DENO_PATH env var (absolute path)
+    2. System PATH (System.find_executable/1)
+  """
+
+  @timeout_ms 30_000
+
+  @type result ::
+          {:ok, map()}
+          | {:error,
+             %{
+               classification:
+                 :deno_missing | :runner_missing | :js_error | :bad_output | :timeout,
+               body: String.t() | map() | nil
+             }}
+
+  @doc """
+  Invoke `tool_name` on the cartridge at `mod_js_path` with `args`.
+
+  Returns `{:ok, data_map}` on success or `{:error, info_map}` on failure.
+  """
+  @spec invoke(String.t(), String.t() | nil, map()) :: result()
+  def invoke(mod_js_path, tool_name, args) do
+    with {:deno, deno} when deno != nil <- {:deno, deno_path()},
+         {:runner, runner} when runner != nil <- {:runner, runner_path()},
+         {:mod, true} <- {:mod, File.regular?(mod_js_path)} do
+      args_json = Jason.encode!(args)
+
+      cmd_args = [
+        "run",
+        "--allow-net",
+        "--allow-env",
+        "--allow-read",
+        runner,
+        mod_js_path,
+        tool_name || "",
+        args_json
+      ]
+
+      task = Task.async(fn -> System.cmd(deno, cmd_args, stderr_to_stdout: true) end)
+
+      case Task.yield(task, @timeout_ms) || Task.shutdown(task, :brutal_kill) do
+        {:ok, {stdout, 0}} ->
+          parse_output(stdout)
+
+        {:ok, {stderr, _code}} ->
+          body = try_decode(String.trim(stderr))
+          {:error, %{classification: :js_error, body: body}}
+
+        nil ->
+          {:error, %{classification: :timeout, body: "JS invocation timed out after #{@timeout_ms}ms"}}
+      end
+    else
+      {:deno, nil} ->
+        {:error,
+         %{
+           classification: :deno_missing,
+           body: "deno binary not found — install Deno or set DENO_PATH env var"
+         }}
+
+      {:runner, nil} ->
+        {:error,
+         %{
+           classification: :runner_missing,
+           body: "priv/js_runner.js not found — check the Elixir release priv directory"
+         }}
+
+      {:mod, false} ->
+        {:error,
+         %{
+           classification: :mod_missing,
+           body: "mod.js not found at #{mod_js_path}"
+         }}
+    end
+  end
+
+  # ── internals ─────────────────────────────────────────────────────────────
+
+  defp parse_output(stdout) do
+    case Jason.decode(String.trim(stdout)) do
+      {:ok, %{"status" => status, "data" => data}} when status in 200..299 ->
+        {:ok, data}
+
+      {:ok, %{"status" => status, "data" => data}} ->
+        # Application-level error returned by handleTool (4xx, 5xx)
+        {:error, %{classification: :js_error, body: data, status: status}}
+
+      {:ok, other} ->
+        {:ok, other}
+
+      {:error, _} ->
+        {:error, %{classification: :bad_output, body: String.trim(stdout)}}
+    end
+  end
+
+  defp try_decode(text) do
+    case Jason.decode(text) do
+      {:ok, m} -> m
+      _ -> text
+    end
+  end
+
+  @spec deno_path() :: String.t() | nil
+  defp deno_path do
+    env = System.get_env("DENO_PATH")
+
+    cond do
+      is_binary(env) and File.regular?(env) -> env
+      true -> System.find_executable("deno")
+    end
+  end
+
+  @spec runner_path() :: String.t() | nil
+  defp runner_path do
+    priv =
+      case :code.priv_dir(:boj_rest) do
+        {:error, _} -> nil
+        dir -> Path.join(to_string(dir), "js_runner.js")
+      end
+
+    # Dev fallback: walk up from this file to the elixir/ project root.
+    dev_fallback =
+      __DIR__
+      |> Path.join("../../../priv/js_runner.js")
+      |> Path.expand()
+
+    cond do
+      is_binary(priv) and File.regular?(priv) -> priv
+      File.regular?(dev_fallback) -> dev_fallback
+      true -> nil
+    end
+  end
+end

elixir/lib/boj_rest/router.ex

@@ -63,21 +63,26 @@ defmodule BojRest.Router do
   post "/cartridge/:name/invoke" do
     case BojRest.Catalog.get(name) do
       {:ok, cart} ->
-        so_path = cartridge_so_path(cart)
         tool = Map.get(conn.body_params || %{}, "tool")
         args = Map.get(conn.body_params || %{}, "arguments") || %{}
 
-        case BojRest.Invoker.invoke(so_path, tool, args) do
-          {:ok, result} ->
-            json(conn, 200, result)
-
-          {:error, info} ->
-            json(conn, 500, %{
-              error: "invocation-failed",
-              cartridge: name,
-              tool: tool,
-              info: info
-            })
+        if is_nil(tool) do
+          json(conn, 400, %{error: "missing-tool-field", cartridge: name})
+        else
+          result = dispatch(cart, tool, args)
+
+          case result do
+            {:ok, data} ->
+              json(conn, 200, data)
+
+            {:error, info} ->
+              json(conn, 500, %{
+                error: "invocation-failed",
+                cartridge: name,
+                tool: tool,
+                info: info
+              })
+          end
         end
 
       :not_found ->
@@ -95,14 +100,31 @@ defmodule BojRest.Router do
     |> Plug.Conn.send_resp(status, Jason.encode!(body))
   end
 
-  # Derive the expected shared-library path from a cartridge entry.
-  # Each cartridge builds its .so under `cartridges/<name>/ffi/zig-out/lib/lib<name>_mcp.so`.
+  # Dispatch to the correct invoker based on whether the cartridge has an FFI
+  # (Zig .so) or a JS (mod.js) implementation.
+  #
+  # cartridge.json with "ffi" key → Zig .so via boj-invoke CLI
+  # cartridge.json without "ffi"  → JS mod.js via Deno (JsInvoker)
+  defp dispatch(cart, tool, args) do
+    if Map.has_key?(cart, "ffi") do
+      BojRest.Invoker.invoke(cartridge_so_path(cart), tool, args)
+    else
+      BojRest.JsInvoker.invoke(cartridge_mod_path(cart), tool, args)
+    end
+  end
+
+  # Read .so path directly from the manifest's ffi.so_path field.
   defp cartridge_so_path(cart) do
-    name = Map.get(cart, "name") || "unknown"
     root = Application.get_env(:boj_rest, :cartridges_root)
-    Path.join([root, name, "ffi", "zig-out", "lib", "lib#{name_to_lib(name)}.so"])
+    name = Map.get(cart, "name")
+    so_rel = get_in(cart, ["ffi", "so_path"])
+    Path.join([root, name, so_rel])
   end
 
-  # cartridge name "aerie-mcp" -> lib name fragment "aerie_mcp"
-  defp name_to_lib(name), do: String.replace(name, "-", "_")
+  # mod.js lives at <cartridges_root>/<name>/mod.js by convention.
+  defp cartridge_mod_path(cart) do
+    root = Application.get_env(:boj_rest, :cartridges_root)
+    name = Map.get(cart, "name")
+    Path.join([root, name, "mod.js"])
+  end
 end

elixir/priv/js_runner.js

@@ -0,0 +1,67 @@
+// SPDX-License-Identifier: PMPL-1.0-or-later
+// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+//
+// js_runner.js — thin Deno harness that imports a cartridge mod.js and calls
+// handleTool(toolName, args), writing { status, data } JSON to stdout.
+//
+// Invoked by BojRest.JsInvoker as:
+//   deno run --allow-net --allow-env --allow-read js_runner.js <abs_mod_path> <tool_name> <args_json>
+//
+// Exit codes:
+//   0  — handleTool returned (success or application-level error in data)
+//   1  — runner itself failed (bad args, import error, unhandled throw)
+
+const [modPath, toolName, argsJson] = Deno.args;
+
+if (!modPath || !toolName) {
+  console.error(JSON.stringify({
+    status: 400,
+    data: { error: "js_runner requires: <mod_path> <tool_name> [args_json]" },
+  }));
+  Deno.exit(1);
+}
+
+let args = {};
+if (argsJson) {
+  try {
+    args = JSON.parse(argsJson);
+  } catch (_) {
+    console.error(JSON.stringify({
+      status: 400,
+      data: { error: `args_json is not valid JSON: ${argsJson}` },
+    }));
+    Deno.exit(1);
+  }
+}
+
+// Dynamic import: convert absolute path to file URL so Deno resolves it
+// correctly on all platforms without needing --allow-import-host.
+const modUrl = modPath.startsWith("/") ? `file://${modPath}` : modPath;
+
+try {
+  const mod = await import(modUrl);
+
+  if (typeof mod.handleTool !== "function") {
+    console.error(JSON.stringify({
+      status: 500,
+      data: { error: `${modPath} does not export handleTool` },
+    }));
+    Deno.exit(1);
+  }
+
+  const result = await mod.handleTool(toolName, args);
+
+  // Ensure result always has the expected shape { status, data }
+  if (result && typeof result.status === "number" && "data" in result) {
+    console.log(JSON.stringify(result));
+  } else {
+    // handleTool returned something unusual — wrap it
+    console.log(JSON.stringify({ status: 200, data: result }));
+  }
+} catch (e) {
+  console.error(JSON.stringify({
+    status: 500,
+    data: { error: `handleTool threw: ${e.message}`, stack: e.stack },
+  }));
+  Deno.exit(1);
+}