@creeperhost/modlens-mcp 1.6.23 → 1.6.26

package/scripts/build-runtime-agent.mjs

@@ -1,7 +1,9 @@
-import { mkdir, mkdtemp, readdir, writeFile, rm } from "node:fs/promises";
+import { mkdir, mkdtemp, readdir, readFile, writeFile, rm } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import AdmZip from "adm-zip";
 
 const root = fileURLToPath(new URL("..", import.meta.url));
 const scratch = join(root, ".scratch");
@@ -9,10 +11,29 @@ await mkdir(scratch, { recursive: true });
 // A clean output directory prevents removed/renamed classes leaking into the JAR.
 const build = await mkdtemp(join(scratch, "runtime-build-"));
 const output = join(root, "dist/runtime");
+const asmJar = join(root, "runtime-agent/vendor/asm-9.9.1.jar");
+const asmSha256 = "6f3828a215c920059a5efa2fb55c233d6c54ec5cadca99ce1b1bdd10077c7ddd";
+const relocate = (bytes) => {
+    const source = Buffer.from("org/objectweb/asm");
+    const target = Buffer.from("io/modlens/asm/v1");
+    if (source.length !== target.length) throw new Error("ASM relocation must preserve class-file lengths");
+    const output = Buffer.from(bytes);
+    for (let at = output.indexOf(source); at !== -1; at = output.indexOf(source, at + target.length))
+        target.copy(output, at);
+    const dottedSource = Buffer.from("org.objectweb.asm");
+    const dottedTarget = Buffer.from("io.modlens.asm.v1");
+    for (let at = output.indexOf(dottedSource); at !== -1; at = output.indexOf(dottedSource, at + dottedTarget.length))
+        dottedTarget.copy(output, at);
+    return output;
+};
 const javaTool = (name) =>
     process.env.JAVA_HOME
         ? join(process.env.JAVA_HOME, "bin", name + (process.platform === "win32" ? ".exe" : ""))
         : name;
+const legacyJavaTool = (name) => {
+    const home = process.env.MODLENS_LEGACY_JAVA_HOME || process.env.JAVA_HOME_17_X64;
+    return home ? join(home, "bin", name + (process.platform === "win32" ? ".exe" : "")) : javaTool(name);
+};
 async function sources(dir) {
     return (
         await Promise.all(
@@ -31,9 +52,45 @@ try {
     const version = execFileSync(javaTool("javac"), ["-version"], { encoding: "utf8" });
     if (Number(/javac (\d+)/.exec(version)?.[1]) < 25)
         throw new Error("Building the runtime agent requires JDK 25+. Set JAVA_HOME.");
+    const legacyFiles = await sources(join(root, "runtime-agent/legacy"));
     const files = await sources(join(root, "runtime-agent/src"));
     // javac argument files avoid Windows command length limits and handle spaces.
-    const args = ["--release", "25", "-d", build, ...files];
+    const vendor = await readFile(asmJar);
+    if (createHash("sha256").update(vendor).digest("hex") !== asmSha256)
+        throw new Error("Vendored ASM checksum mismatch");
+    const legacyArgs = ["--release", "8", "-cp", asmJar, "-d", build, ...legacyFiles];
+    await writeFile(
+        join(build, "legacy.args"),
+        legacyArgs.map((a) => `"${a.replaceAll("\\", "/").replaceAll('"', '\\"')}"`).join("\n"),
+    );
+    execFileSync(legacyJavaTool("javac"), ["@" + join(build, "legacy.args")], { stdio: "inherit" });
+    const jfrFiles = await sources(join(root, "runtime-agent/jfr11"));
+    const jfrArgs = ["--release", "11", "-cp", build, "-d", build, ...jfrFiles];
+    await writeFile(
+        join(build, "jfr.args"),
+        jfrArgs.map((a) => `"${a.replaceAll("\\", "/").replaceAll('"', '\\"')}"`).join("\n"),
+    );
+    execFileSync(legacyJavaTool("javac"), ["@" + join(build, "jfr.args")], { stdio: "inherit" });
+    const classes = async (dir) => (await readdir(dir, { withFileTypes: true })).flatMap((entry) =>
+        entry.isDirectory() ? [join(dir, entry.name)] : entry.name.endsWith(".class") ? [join(dir, entry.name)] : []);
+    const relocateTree = async (dir) => {
+        for (const entry of await classes(dir)) {
+            if (entry.endsWith(".class")) await writeFile(entry, relocate(await readFile(entry)));
+            else await relocateTree(entry);
+        }
+    };
+    await relocateTree(join(build, "io"));
+    const asm = new AdmZip(vendor);
+    for (const entry of asm.getEntries()) {
+        if (!entry.entryName.startsWith("org/objectweb/asm/") || !entry.entryName.endsWith(".class")) continue;
+        const destination = join(build, entry.entryName.replace("org/objectweb/asm/", "io/modlens/asm/v1/"));
+        await mkdir(dirname(destination), { recursive: true });
+        await writeFile(destination, relocate(entry.getData()));
+    }
+    const license = join(build, "META-INF/licenses/ASM.txt");
+    await mkdir(dirname(license), { recursive: true });
+    await writeFile(license, await readFile(join(root, "runtime-agent/vendor/ASM-LICENSE.txt")));
+    const args = ["-cp", build, "-d", build, ...files];
     await writeFile(
         join(build, "javac.args"),
         args.map((a) => `"${a.replaceAll("\\", "/").replaceAll('"', '\\"')}"`).join("\n"),
@@ -44,7 +101,7 @@ try {
         "Manifest-Version: 1.0\nPremain-Class: io.modlens.runtime.Agent\nCan-Redefine-Classes: false\nCan-Retransform-Classes: false\n\n",
     );
     execFileSync(
-        javaTool("jar"),
+        legacyJavaTool("jar"),
         [
             "--create",
             "--file",
@@ -54,6 +111,9 @@ try {
             "-C",
             build,
             "io",
+            "-C",
+            build,
+            "META-INF/licenses",
         ],
         { stdio: "inherit" },
     );

package/scripts/gradle/modlens-runtime.init.gradle

@@ -12,6 +12,6 @@ gradle.projectsEvaluated {
     }
     target.jvmArgs("-javaagent:${config.getProperty('agent')}=${config.getProperty('connection')}")
     // Minecraft 26.3 client startup needs this even without the agent.
-    target.jvmArgs('-XX:StackShadowPages=32')
+    if (config.getProperty('mcVersion', '26.3') == '26.3') target.jvmArgs('-XX:StackShadowPages=32')
     target.jvmArgs("-XX:ErrorFile=${new File(configFile.parentFile, 'hs_err_pid%p.log').absolutePath}")
 }

package/scripts/test-hosted-oauth.mjs

@@ -7,6 +7,8 @@ import { mkdtemp, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
 
 const root = await mkdtemp(join(tmpdir(), 'modlens-oauth-test-'));
 const entry = fileURLToPath(new URL('../dist/server.js', import.meta.url));
@@ -26,13 +28,15 @@ const profiles = new Map();
 let partner = true;
 let subject = 'customer:42';
 let serial = 0;
+let metadataRequests = 0;
 const provider = createServer(async (req, res) => {
     const url = new URL(req.url, issuer);
     const write = (status, data) => { res.writeHead(status, { 'Content-Type': 'application/json' }); res.end(JSON.stringify(data)); };
-    if (url.pathname === '/.well-known/oauth-authorization-server') return write(200, {
-        issuer, authorization_endpoint: issuer + '/authorize', token_endpoint: issuer + '/token',
-        authorization_response_iss_parameter_supported: true,
-    });
+    if (url.pathname === '/.well-known/oauth-authorization-server') {
+        if (++metadataRequests === 1) return write(503, { error: 'temporarily_unavailable', access_token: 'metadata-secret' });
+        return write(200, { issuer, authorization_endpoint: issuer + '/authorize', token_endpoint: issuer + '/token',
+            authorization_response_iss_parameter_supported: true });
+    }
     if (url.pathname === '/authorize') {
         const callback = new URL(url.searchParams.get('redirect_uri'));
         callback.searchParams.set('code', 'fake-code');
@@ -46,6 +50,8 @@ const provider = createServer(async (req, res) => {
         const data = new URLSearchParams(raw);
         if (data.get('grant_type') === 'refresh_token' && !data.get('refresh_token')?.startsWith('upstream-refresh-'))
             return write(400, { error: 'invalid_grant' });
+        if (data.get('grant_type') === 'refresh_token')
+            await new Promise(resolve => setTimeout(resolve, 100));
         if (data.get('grant_type') === 'authorization_code' && data.get('code') !== 'fake-code')
             return write(400, { error: 'invalid_grant' });
         const access = `upstream-${++serial}`;
@@ -96,7 +102,7 @@ const initialize = (access, extra = {}) => fetchManual(resource, { method: 'POST
     protocolVersion: '2025-11-25', capabilities: {}, clientInfo: { name: 'oauth-test', version: '1' },
 } }) });
 let clientId;
-async function login() {
+async function login(expectedName = 'ChatGPT & Codex <test>') {
     const verifier = randomBytes(32).toString('base64url');
     const pkce = createHash('sha256').update(verifier).digest('base64url');
     const callback = 'http://127.0.0.1:54321/callback';
@@ -111,9 +117,19 @@ async function login() {
     const done = await fetchManual(back.headers.get('location'));
     assert.equal(done.status, 200);
     assert.match(done.headers.get('content-security-policy'), /default-src 'none'/);
+    assert.match(done.headers.get('content-security-policy'), /form-action 'self' http:\/\/127\.0\.0\.1:54321;/,
+        'consent form permits its registered OAuth callback after the approval redirect');
     const consentPage = await done.text();
     assert.match(consentPage, /CREEPERHOST/);
     assert.match(consentPage, /Allow access\?/);
+    if (expectedName) {
+        assert.ok(consentPage.includes(expectedName), 'registered application names are displayed and HTML-escaped');
+        assert.match(consentPage, /Name supplied by application/);
+    } else {
+        assert.match(consentPage, /Unnamed application/);
+        assert.match(consentPage, /No application name supplied/);
+    }
+    assert.match(consentPage, /Callback: http:\/\/127\.0\.0\.1:54321/);
     assert.match(consentPage, /Only continue if you started this request/);
     const approval = consentPage.match(/name="approval" value="([^"]+)"/)?.[1];
     assert.ok(approval);
@@ -152,32 +168,70 @@ async function login() {
 }
 try {
     await start();
+    assert.match(serverOutput, /"event":"provider_metadata_retry".*"status":503/,
+        'transient provider discovery failures are logged and retried');
+    assert.match(serverOutput, /"event":"provider_metadata_response".*temporarily_unavailable/,
+        'failed provider responses include a useful body excerpt');
+    assert.ok(!serverOutput.includes('metadata-secret'), 'provider response logging redacts token fields');
     const absent = await fetchManual(resource);
     assert.equal(absent.status, 401);
     assert.match(absent.headers.get('www-authenticate'), /resource_metadata=/);
     const metadata = await (await fetchManual(`http://127.0.0.1:${mcpPort}/.well-known/oauth-protected-resource/mcp`)).json();
     assert.deepEqual(metadata.authorization_servers, [`http://127.0.0.1:${mcpPort}`]);
     const registration = await fetchManual(`http://127.0.0.1:${mcpPort}/oauth/register`, { method: 'POST',
-        headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ redirect_uris: ['http://127.0.0.1:54321/callback'] }) });
+        headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({
+            redirect_uris: ['http://127.0.0.1:54321/callback'], client_name: 'ChatGPT & Codex <test>' }) });
     assert.equal(registration.status, 201);
-    clientId = (await registration.json()).client_id;
+    const registered = await registration.json();
+    assert.equal(registered.client_name, 'ChatGPT & Codex <test>');
+    clientId = registered.client_id;
     const tokens = await login();
     assert.match(tokens.access_token, /^mla_/);
     assert.match(tokens.refresh_token, /^mlr_/);
     assert.equal((await initialize(tokens.access_token)).status, 200);
+    const runtimeClient = new Client({ name: 'hosted-runtime-test', version: '1' });
+    await runtimeClient.connect(new StreamableHTTPClientTransport(new URL(resource), {
+        requestInit: { headers: { Authorization: `Bearer ${tokens.access_token}` } },
+    }));
+    try {
+        const runtime = await runtimeClient.callTool({ name: 'runtime', arguments: {
+            action: 'setup', projectDir: '/local/mod-project', mcVersion: '1.7.10', mode: 'interactive',
+        } });
+        assert.equal(runtime.isError, undefined);
+        const plan = JSON.parse(runtime.content[0].text);
+        assert.equal(plan.executed, false);
+        assert.equal(plan.request.mcVersion, '1.7.10');
+        assert.ok(plan.invocation.arguments.includes('--runtime'));
+    } finally { await runtimeClient.close(); }
     assert.equal((await initialize(tokens.access_token, { 'x-modlens-user-id': 'forged' })).status, 401);
     await stop();
     await start();
     assert.equal((await initialize(tokens.access_token)).status, 200, 'grant survives restart');
-    const refresh = await fetchManual(`http://127.0.0.1:${mcpPort}/oauth/token`, { method: 'POST',
-        headers: { 'Content-Type': 'application/x-www-form-urlencoded' }, body: form({ grant_type: 'refresh_token',
-            client_id: clientId, refresh_token: tokens.refresh_token, resource }) });
-    assert.equal(refresh.status, 200);
-    const rotated = await refresh.json();
+    const refreshes = await Promise.all(Array.from({ length: 4 }, () =>
+        fetchManual(`http://127.0.0.1:${mcpPort}/oauth/token`, { method: 'POST',
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded' }, body: form({ grant_type: 'refresh_token',
+                client_id: clientId, refresh_token: tokens.refresh_token, resource }) })));
+    for (const refresh of refreshes) assert.equal(refresh.status, 200, 'overlapping refresh requests share one rotation');
+    const rotations = await Promise.all(refreshes.map(response => response.json()));
+    assert.equal(new Set(rotations.map(response => response.refresh_token)).size, 1);
+    assert.equal((serverOutput.match(/"event":"refresh_issued"/g) ?? []).length, 1);
+    assert.equal((serverOutput.match(/"event":"refresh_joined"/g) ?? []).length, 3);
+    const rotated = rotations[0];
     const replay = await fetchManual(`http://127.0.0.1:${mcpPort}/oauth/token`, { method: 'POST',
         headers: { 'Content-Type': 'application/x-www-form-urlencoded' }, body: form({ grant_type: 'refresh_token',
             client_id: clientId, refresh_token: tokens.refresh_token }) });
     assert.equal(replay.status, 400);
+    const oldRefreshRef = createHash('sha256').update(tokens.refresh_token).digest('hex').slice(0, 12);
+    const refreshEvents = serverOutput.split('\n').filter(line => line.includes('[modlens] oauth '))
+        .map(line => JSON.parse(line.slice(line.indexOf('[modlens] oauth ') + '[modlens] oauth '.length)));
+    const issued = refreshEvents.find(event => event.event === 'refresh_issued');
+    const rejected = refreshEvents.find(event => event.event === 'refresh_rejected');
+    assert.equal(issued.previousRefreshRef, oldRefreshRef);
+    assert.equal(rejected.refreshRef, oldRefreshRef);
+    assert.equal(rejected.reason, 'not_current_or_missing');
+    assert.equal(issued.grant.length, 12);
+    assert.ok(refreshEvents.filter(event => event.event.startsWith('refresh_'))
+        .every(event => /^[a-f0-9]{12}$/.test(event.instance)));
     const firstSession = await initialize(rotated.access_token);
     assert.equal(firstSession.status, 200);
     const sessionId = firstSession.headers.get('mcp-session-id');
@@ -191,6 +245,10 @@ try {
     partner = false;
     assert.equal((await initialize(rotated.access_token)).status, 403);
     assert.equal((await initialize(rotated.access_token)).status, 401);
+    assert.match(serverOutput, /"event":"grant_revoked".*"reason":"profile_unauthorized"/);
+    assert.match(serverOutput, /"event":"grant_revoked".*"reason":"profile_access_denied"/);
+    for (const secret of [tokens.refresh_token, rotated.refresh_token, rotated.access_token])
+        assert.ok(!serverOutput.includes(secret), 'refresh diagnostics must not log bearer material');
     const denied = await fetchManual(`http://127.0.0.1:${mcpPort}/oauth/authorize?client_id=bad`);
     assert.equal(denied.status, 400);
     await stop();
@@ -200,6 +258,11 @@ try {
     const generalAccount = await login();
     assert.equal((await initialize(generalAccount.access_token)).status, 200,
         'self-hosted mode accepts a valid account without a claim rule');
+    const unnamedRegistration = await fetchManual(`http://127.0.0.1:${mcpPort}/oauth/register`, { method: 'POST',
+        headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ redirect_uris: ['http://127.0.0.1:54321/callback'] }) });
+    assert.equal(unnamedRegistration.status, 201);
+    clientId = (await unnamedRegistration.json()).client_id;
+    await login(null);
     console.log('Hosted OAuth discovery, registration, sign-in, persistence, refresh, replay, session, revocation, partner, gateway-header and self-hosted checks passed.');
 } finally {
     await stop();

package/scripts/test-hosted-policy.mjs

@@ -29,6 +29,7 @@ const env = { ...process.env, MCP_PORT: String(port), MCP_HOST: "127.0.0.1", MOD
     MODLENS_HOSTED_DAILY_BYTES: "15000", MODLENS_HOSTED_PERIOD_BYTES: "100000",
     MODLENS_HOSTED_DAILY_REQUESTS: "1000", MODLENS_HOSTED_MINUTE_REQUESTS: "120",
     MODLENS_HOSTED_RESPONSE_BYTES: "131072", MODLENS_AUTO_EMBED: "0", MODLENS_AUTO_GRAPH: "0" };
+env.MODLENS_OPENAI_DOMAIN_CHALLENGE = "test-openai-domain-token";
 const source = Array.from({ length: 600 }, (_, i) => `// Synthetic fixture line ${i + 1}`).join("\n");
 const fixtureDir = join(env.MODLENS_CACHE_ROOT, "mc-decompiled-named", "1.21.1", "example");
 await mkdir(fixtureDir, { recursive: true });
@@ -67,10 +68,35 @@ const read = (client, startLine = 1) => client.callTool({ name: "mc_source", arg
 let passed = false;
 try {
     await start();
+    const domainChallenge = await fetch(new URL("/.well-known/openai-apps-challenge", endpoint));
+    assert.equal(domainChallenge.status, 200);
+    assert.equal(domainChallenge.headers.get("content-type"), "text/plain; charset=utf-8");
+    assert.equal(await domainChallenge.text(), env.MODLENS_OPENAI_DOMAIN_CHALLENGE);
     const unauthorized = await fetch(endpoint, { method: "POST", headers: { "x-modlens-user-id": "spoof" }, body: "{}" });
     assert.equal(unauthorized.status, 401);
     const publicUser = await connect("public-developer");
     const publicTools = await publicUser.client.listTools();
+    const expectedTools = ["report_issue", "runtime", "mod_license", "mod", "mod_bytecode", "mod_mixins",
+        "platform", "modpacks_ch", "mc_versions", "mc_source", "mappings", "docs", "primers",
+        "mc_registry", "mc_data", "mc_files", "mod_jar", "mod_data", "mod_tags", "mixin_scan",
+        "gradle", "project", "reports", "pack_tools", "analyze_crash_log", "find_missing_deps"];
+    assert.deepEqual(publicTools.tools.map(t => t.name).sort(), expectedTools.sort());
+    for (const tool of publicTools.tools) {
+        assert.ok(tool.title, `${tool.name} has no title`);
+        assert.ok(tool.description, `${tool.name} has no description`);
+        for (const hint of ["readOnlyHint", "openWorldHint", "destructiveHint"])
+            assert.equal(typeof tool.annotations?.[hint], "boolean", `${tool.name} has no ${hint}`);
+    }
+    const tool = name => publicTools.tools.find(t => t.name === name);
+    for (const [name, fields] of Object.entries({
+        mod: ["jarPath", "directory", "outputDir", "bundlePath"],
+        mappings: ["inputJar", "outputJar"], project: ["bundlePath"],
+        reports: ["savePath"], pack_tools: ["scriptsDir", "configDir"],
+    })) for (const field of fields)
+        assert.ok(!(field in tool(name).inputSchema.properties), `${name} advertises host-only ${field}`);
+    assert.equal(tool("project").annotations.destructiveHint, true);
+    assert.equal(tool("mc_source").annotations.readOnlyHint, false);
+    assert.equal(tool("report_issue").annotations.readOnlyHint, true);
     const publicMc = publicTools.tools.find(t => t.name === "mc_source");
     assert.ok(publicMc.inputSchema.properties.action.enum.includes("source_info"));
     assert.ok(publicMc.inputSchema.properties.action.enum.includes("index_status"));

package/scripts/test-package.mjs

@@ -137,6 +137,10 @@ try {
         const configuredRuntime = runtime("--request-file",runtimeRequest);
         assert.equal(configuredRuntime.state,"configured");
         assert.deepEqual(configuredRuntime.vmOptions,[configuredRuntime.vmOption,"-XX:StackShadowPages=32"]);
+        writeFileSync(runtimeRequest,JSON.stringify({action:"setup",projectDir:runtimeProject,mcVersion:"1.7.10",mode:"interactive"}));
+        const legacyRuntime = runtime("--request-file",runtimeRequest);
+        assert.deepEqual(legacyRuntime.vmOptions,[legacyRuntime.vmOption]);
+        assert.equal(legacyRuntime.mcVersion,"1.7.10");
         assert.equal(runtime("status").projects.length,1);
         assert.deepEqual(runtime("sessions"),[]);
         assert.ok(!existsSync(join(runtimeHome,"data")),"Runtime helper must not create a source database");

package/scripts/test-runtime-glfw.mjs

@@ -0,0 +1,81 @@
+import assert from 'node:assert/strict';
+import { spawn, execFileSync } from 'node:child_process';
+import { once } from 'node:events';
+import { mkdtemp, mkdir, readdir, writeFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, delimiter } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { RuntimeHub } from '../dist/runtime/hub.js';
+
+const repo = fileURLToPath(new URL('..', import.meta.url));
+const javaHome = process.env.MODLENS_TEST_JAVA_HOME;
+const native = Boolean(process.env.MODLENS_GLFW_CLASSPATH);
+if (!javaHome) throw new Error('Set MODLENS_TEST_JAVA_HOME to a Java 17 or newer JDK');
+const executable = name => join(javaHome, 'bin', name + (process.platform === 'win32' ? '.exe' : ''));
+const root = await mkdtemp(join(tmpdir(), 'modlens-runtime-glfw-'));
+const project = join(root, 'glfw-project');
+const hub = new RuntimeHub(join(root, 'cache'));
+let game;
+let gameDone;
+try {
+    await mkdir(join(project, 'gradle', 'wrapper'), { recursive: true });
+    await writeFile(join(project, 'gradle', 'wrapper', 'gradle-wrapper.jar'), 'fixture');
+    const setup = await hub.setup(project, native ? 'hidden' : 'observe', 'runClient', true, '1.20.1');
+    assert.deepEqual(setup.vmOptions, [setup.vmOption]);
+    const files = [];
+    if (native) files.push(join(repo, 'runtime-agent/test/io/modlens/runtime/NativeGlfwSmoke.java'));
+    else {
+        const fixture = join(repo, 'runtime-agent/test/legacy-fixture/org/lwjgl/glfw');
+        files.push(...(await readdir(fixture)).filter(name => name.endsWith('.java')).map(name => join(fixture, name)));
+        files.push(join(repo, 'runtime-agent/test/legacy-fixture/org/lwjgl/opengl/GL11.java'));
+        files.push(join(repo, 'runtime-agent/test/io/modlens/runtime/GlfwSmoke.java'));
+    }
+    const classpath = [root, process.env.MODLENS_GLFW_CLASSPATH].filter(Boolean).join(delimiter);
+    execFileSync(executable('javac'), ['-cp', classpath, '-d', root, ...files]);
+    game = spawn(executable('java'), [`-Djava.io.tmpdir=${root}`, setup.vmOption, '-cp', classpath,
+        native ? 'io.modlens.runtime.NativeGlfwSmoke' : 'io.modlens.runtime.GlfwSmoke', root],
+        { stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
+    let output = '', error = '';
+    game.stdout.on('data', bytes => { output += bytes; });
+    game.stderr.on('data', bytes => { error += bytes; });
+    gameDone = once(game, 'exit');
+    const deadline = Date.now() + 20000;
+    let session;
+    while (Date.now() < deadline) {
+        session = (await hub.list()).find(s => s.capabilities.target === '1.20.1' && s.capabilities.inputBackend === 'glfw');
+        if (session) break;
+        await new Promise(resolve => setTimeout(resolve, 100));
+    }
+    assert.ok(session, error || 'GLFW agent did not connect');
+    assert.equal(session.capabilities.jfr, true, JSON.stringify(await hub.events()));
+    const act = async command => {
+        try { return await hub.command(session.sessionId, command); }
+        catch (cause) { throw new Error(`${cause}\n${JSON.stringify(await hub.events())}\n${error}`); }
+    };
+    assert.equal((await act({ type: 'key', key: 'W', down: true, holdMs: 100 })).state, 'event_delivered');
+    assert.equal((await act({ type: 'mouse_button', button: 1, down: true, holdMs: 100 })).state, 'event_delivered');
+    assert.equal((await act({ type: 'mouse_move', x: 12, y: 5, relative: false })).state, 'event_delivered');
+    assert.equal((await act({ type: 'scroll', x: 0, y: 1 })).state, 'event_delivered');
+    assert.equal((await act({ type: 'text', text: 'A' })).state, 'event_delivered');
+    const frame = await act({ type: 'screenshot' });
+    assert.equal((await hub.artifact(session.sessionId, frame.artifact)).mimeType, 'image/png');
+    const recording = await act({ type: 'recording' });
+    assert.match(recording.artifact, /\.jfr$/);
+    const allocations = await act({ type: 'allocations', packagePrefix: 'io.modlens.runtime' });
+    const report = await hub.artifact(session.sessionId, allocations.artifact);
+    assert.equal(JSON.parse(report.text).kind, 'sampled_allocation_pressure');
+    assert.equal((await act({ type: 'mode', mode: 'hidden' })).mode, 'hidden');
+    await writeFile(join(root, 'finish'), 'done');
+    assert.equal((await gameDone)[0], 0, error);
+    for (const marker of ['KEY 87 1', 'BUTTON 0 1', 'MOVE 12.0 5.0', 'SCROLL 0.0 1.0', 'CHAR 65'])
+        assert.match(output, new RegExp(marker.replaceAll('.', '\\.')));
+    assert.equal((output.match(/KEY 87 1/g) ?? []).length, 1, 'physical key events must be filtered in observe mode');
+    console.log(`PASS: one packaged agent hooks ${native ? 'native ' : ''}GLFW callbacks, filters physical input, injects commands, captures a frame, and hides the window`);
+} finally {
+    if (game && game.exitCode === null) {
+        game.kill();
+        await gameDone?.catch(() => {});
+    }
+    await hub.close();
+    await rm(root, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
+}

package/scripts/test-runtime-legacy.mjs

@@ -0,0 +1,71 @@
+import assert from 'node:assert/strict';
+import { spawn, execFileSync } from 'node:child_process';
+import { once } from 'node:events';
+import { mkdtemp, mkdir, writeFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { RuntimeHub } from '../dist/runtime/hub.js';
+
+const repo = fileURLToPath(new URL('..', import.meta.url));
+const javaHome = process.env.MODLENS_TEST_JAVA_HOME || process.env.MODLENS_JAVA8_HOME;
+if (!javaHome) throw new Error('Set MODLENS_TEST_JAVA_HOME to a Java 8 or newer JDK');
+const executable = name => join(javaHome, 'bin', name + (process.platform === 'win32' ? '.exe' : ''));
+const root = await mkdtemp(join(tmpdir(), 'modlens-runtime-legacy-'));
+const project = join(root, 'legacy-project');
+const hub = new RuntimeHub(join(root, 'cache'));
+let game;
+try {
+    await mkdir(join(project, 'gradle', 'wrapper'), { recursive: true });
+    await writeFile(join(project, 'gradle', 'wrapper', 'gradle-wrapper.jar'), 'fixture');
+    const setup = await hub.setup(project, 'interactive', 'runClient', true, '1.7.10');
+    assert.deepEqual(setup.vmOptions, [setup.vmOption]);
+    const fixture = join(repo, 'runtime-agent/test/legacy-fixture');
+    execFileSync(executable('javac'), ['-d', root,
+        join(fixture, 'org/lwjgl/opengl/Display.java'),
+        join(fixture, 'org/lwjgl/opengl/GL11.java'),
+        join(fixture, 'org/lwjgl/input/Keyboard.java'),
+        join(fixture, 'org/lwjgl/input/Mouse.java'),
+        join(fixture, 'net/minecraft/CrashReport.java'),
+        join(repo, 'runtime-agent/test/io/modlens/runtime/LegacySmoke.java')]);
+    game = spawn(executable('java'), [setup.vmOption, '-cp', root,
+        'io.modlens.runtime.LegacySmoke', root], { stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
+    let gameError = '', gameOutput = '';
+    game.stderr.on('data', bytes => { gameError += bytes; });
+    game.stdout.on('data', bytes => { gameOutput += bytes; });
+    const gameDone = once(game, 'exit');
+    const deadline = Date.now() + 20000;
+    let session;
+    while (Date.now() < deadline) {
+        session = (await hub.list()).find(s => s.capabilities.target === '1.7.10' && s.capabilities.inputBackend === 'lwjgl2');
+        if (session) break;
+        await new Promise(resolve => setTimeout(resolve, 100));
+    }
+    assert.ok(session, gameError || 'Legacy agent did not connect');
+    assert.equal(session.capabilities.inputBackend, 'lwjgl2');
+    assert.equal(session.capabilities.threads, true);
+    assert.ok(session.javaVersion);
+    assert.ok(session.metrics.heapUsed > 0);
+    const threads = await hub.command(session.sessionId, { type: 'threads' });
+    const report = await hub.artifact(session.sessionId, threads.artifact);
+    assert.match(report.text, /ModLens telemetry/);
+    assert.equal((await hub.command(session.sessionId, { type: 'mode', mode: 'observe' })).mode, 'observe');
+    assert.equal((await hub.command(session.sessionId, { type: 'key', key: 'W', down: true, holdMs: 100 })).state, 'event_delivered');
+    assert.equal((await hub.command(session.sessionId, { type: 'mouse_button', button: 1, down: true, holdMs: 100 })).state, 'event_delivered');
+    assert.equal((await hub.command(session.sessionId, { type: 'scroll', y: 1, x: 0 })).state, 'event_delivered');
+    const frame = await hub.command(session.sessionId, { type: 'screenshot' });
+    assert.equal((await hub.artifact(session.sessionId, frame.artifact)).mimeType, 'image/png');
+    assert.match(gameOutput, /KEY 17 true/);
+    assert.match(gameOutput, /MOUSE 0 0/);
+    assert.match(gameOutput, /MOUSE -1 120/);
+    const events = await hub.events();
+    assert.ok(events.events.some(e => e.type === 'agent_started'));
+    assert.ok(events.events.some(e => e.type === 'minecraft_crash'));
+    await writeFile(join(root, 'finish'), 'done');
+    assert.equal((await gameDone)[0], 0, gameError);
+    console.log(`PASS: one packaged agent runs on Java ${session.javaVersion}, hooks LWJGL2 keyboard/mouse events and screenshots, and reports diagnostics`);
+} finally {
+    if (game && game.exitCode === null) game.kill();
+    await hub.close();
+    await rm(root, { recursive: true, force: true });
+}

package/scripts/test-runtime-lwjgl2-real.mjs

@@ -0,0 +1,59 @@
+import assert from 'node:assert/strict';
+import { spawn, execFileSync } from 'node:child_process';
+import { once } from 'node:events';
+import { mkdtemp, mkdir, writeFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, delimiter } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { RuntimeHub } from '../dist/runtime/hub.js';
+
+const repo = fileURLToPath(new URL('..', import.meta.url));
+const javaHome = process.env.MODLENS_TEST_JAVA_HOME;
+const lwjgl = process.env.MODLENS_LWJGL2_CLASSPATH;
+if (!javaHome || !lwjgl) throw new Error('Set MODLENS_TEST_JAVA_HOME and MODLENS_LWJGL2_CLASSPATH');
+const bin = name => join(javaHome, 'bin', name + (process.platform === 'win32' ? '.exe' : ''));
+const root = await mkdtemp(join(tmpdir(), 'modlens-real-lwjgl2-'));
+const project = join(root, 'project');
+const agent = join(repo, 'dist/runtime/modlens-agent.jar');
+const classpath = [root, agent, lwjgl].join(delimiter);
+const hub = new RuntimeHub(join(root, 'cache'));
+let game;
+try {
+    await mkdir(join(project, 'gradle', 'wrapper'), { recursive: true });
+    await writeFile(join(project, 'gradle', 'wrapper', 'gradle-wrapper.jar'), 'fixture');
+    const setup = await hub.setup(project, 'observe', 'runClient', true, '1.7.10');
+    execFileSync(bin('javac'), ['-cp', classpath, '-d', root,
+        join(repo, 'runtime-agent/test/io/modlens/runtime/RealLwjgl2Smoke.java')]);
+    game = spawn(bin('java'), [setup.vmOption, '-cp', classpath,
+        'io.modlens.runtime.RealLwjgl2Smoke', root],
+        { stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
+    let output = '', error = '';
+    game.stdout.on('data', bytes => { output += bytes; });
+    game.stderr.on('data', bytes => { error += bytes; });
+    const done = once(game, 'exit');
+    const deadline = Date.now() + 20000;
+    let session;
+    while (Date.now() < deadline) {
+        session = (await hub.list()).find(s => s.capabilities.inputBackend === 'lwjgl2');
+        if (session) break;
+        await new Promise(resolve => setTimeout(resolve, 100));
+    }
+    assert.ok(session, error || 'LWJGL2 agent did not connect');
+    assert.equal((await hub.command(session.sessionId, { type: 'key', key: 'W', down: true, holdMs: 500 })).state, 'event_delivered');
+    assert.equal((await hub.command(session.sessionId, { type: 'mouse_button', button: 1, down: true, holdMs: 500 })).state, 'event_delivered');
+    assert.equal((await hub.command(session.sessionId, { type: 'scroll', x: 0, y: 1 })).state, 'event_delivered');
+    const events = (await hub.events()).events;
+    assert.ok(events.some(e => e.type === 'hooks_installed' && e.data.class === 'org/lwjgl/input/Keyboard'));
+    assert.ok(events.some(e => e.type === 'hooks_installed' && e.data.class === 'org/lwjgl/input/Mouse'));
+    assert.ok(events.some(e => e.type === 'hooks_installed' && e.data.class === 'org/lwjgl/opengl/Display'));
+    assert.match(output, /KEY 17 true/);
+    assert.match(output, /MOUSE 0 0/);
+    assert.match(output, /MOUSE -1 120/);
+    await writeFile(join(root, 'finish'), 'done');
+    assert.equal((await done)[0], 0, error);
+    console.log('PASS: one packaged Java 8 agent instruments actual LWJGL2 keyboard and mouse classes');
+} finally {
+    if (game && game.exitCode === null) game.kill();
+    await hub.close();
+    await rm(root, { recursive: true, force: true });
+}