From 099584676b44fdfb17f4b75b2ac00dbf00a7a0c4 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Thu, 4 Jun 2026 16:22:24 -0400
Subject: [PATCH] docs: document extension loader tests

---
 .../extensions/loader.bun-virtual-modules.test.ts         | 3 +++
 src/agents/sessions/extensions/loader.native-js.test.ts   | 8 ++++++++
 src/agents/sessions/extensions/loader.test.ts             | 4 ++++
 3 files changed, 15 insertions(+)

diff --git a/src/agents/sessions/extensions/loader.bun-virtual-modules.test.ts b/src/agents/sessions/extensions/loader.bun-virtual-modules.test.ts
index 14fc4720b671..386f9cdfd1a7 100644
--- a/src/agents/sessions/extensions/loader.bun-virtual-modules.test.ts
+++ b/src/agents/sessions/extensions/loader.bun-virtual-modules.test.ts
@@ -1,3 +1,4 @@
+// Bun binary extension loader tests cover virtual SDK modules passed to jiti.
 import { mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -56,6 +57,8 @@ afterEach(async () => {
 
 describe("loadExtensions in Bun binary mode", () => {
   it("virtualizes scoped and unscoped SDK module ids", async () => {
+    // Bundled Bun binaries cannot rely on Node resolution for SDK aliases, so
+    // both historical and scoped module ids are registered as virtual modules.
     expect(virtualModulesCase.errors).toEqual([]);
     expect(virtualModulesCase.virtualModuleIds).toEqual(
       expect.arrayContaining([
diff --git a/src/agents/sessions/extensions/loader.native-js.test.ts b/src/agents/sessions/extensions/loader.native-js.test.ts
index 87b131b28fb9..0cb204f5b478 100644
--- a/src/agents/sessions/extensions/loader.native-js.test.ts
+++ b/src/agents/sessions/extensions/loader.native-js.test.ts
@@ -1,3 +1,5 @@
+// Native JavaScript extension loader tests cover when compiled JS can bypass
+// jiti and when alias-sensitive graphs must keep jiti resolution.
 import { mkdtemp, rm, stat, utimes, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -70,6 +72,8 @@ export default async function extension(api) {
   });
 
   it("reloads native JavaScript extensions when the file changes without stat-key drift", async () => {
+    // Native dynamic imports use a content-aware cache key so same-size,
+    // same-mtime edits still reload the extension module.
     const { loadExtensions } = await import("./loader.js");
     const dir = await mkdtemp(join(tmpdir(), "openclaw-extension-js-"));
     tempDirs.push(dir);
@@ -184,6 +188,8 @@ export default async function extension(api) {
   });
 
   it("keeps SDK-alias JavaScript extensions on one shared jiti loader", async () => {
+    // SDK aliases need jiti's virtual resolution, but one shared loader keeps
+    // multi-extension imports consistent and cheap.
     const { loadExtensions } = await import("./loader.js");
     const dir = await mkdtemp(join(tmpdir(), "openclaw-extension-js-"));
     tempDirs.push(dir);
@@ -236,6 +242,8 @@ module.exports = async function(api) {
   });
 
   it("keeps multi-file JavaScript extensions on jiti for graph-wide aliases", async () => {
+    // Alias detection walks relative helper files; a clean entrypoint can still
+    // need jiti when its dependency graph imports SDK/TypeBox aliases.
     const { loadExtensions } = await import("./loader.js");
     const dir = await mkdtemp(join(tmpdir(), "openclaw-extension-js-"));
     tempDirs.push(dir);
diff --git a/src/agents/sessions/extensions/loader.test.ts b/src/agents/sessions/extensions/loader.test.ts
index 8c8c69edb26c..561132bf2715 100644
--- a/src/agents/sessions/extensions/loader.test.ts
+++ b/src/agents/sessions/extensions/loader.test.ts
@@ -1,3 +1,5 @@
+// Extension loader tests cover SDK import resolution for jiti-loaded TypeScript
+// extensions.
 import { mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -12,6 +14,8 @@ afterEach(async () => {
 
 describe("loadExtensions", () => {
   it("resolves plugin SDK subpaths in jiti-loaded extensions", async () => {
+    // Extensions import both public SDK helpers and runtime helper subpaths; the
+    // loader must route those aliases without package-manager involvement.
     const dir = await mkdtemp(join(tmpdir(), "openclaw-extension-sdk-"));
     tempDirs.push(dir);
     const extensionPath = join(dir, "extension.ts");