@langchain/quickjs 0.3.0 → 0.4.0

package/dist/index.d.cts

@@ -6,9 +6,9 @@ import { AnyBackendProtocol, BackendFactory, SkillMetadata } from "deepagents";
 
 //#region src/types.d.ts
 /**
- * Configuration options for the REPL middleware.
+ * Configuration options for the Code Interpreter middleware.
  */
-interface REPLMiddlewareOptions {
+interface CodeInterpreterMiddlewareOptions {
   /**
    * Enable programmatic tool calling from within the REPL.
    *
@@ -121,9 +121,9 @@ interface SkillsContext {
 //#endregion
 //#region src/middleware.d.ts
 /**
- * Create the REPL middleware.
+ * Create the Code Interpreter middleware.
  */
-declare function createREPLMiddleware(options?: REPLMiddlewareOptions): AgentMiddleware<undefined, undefined, unknown, readonly [_$langchain.DynamicStructuredTool<z.ZodObject<{
+declare function createCodeInterpreterMiddleware(options?: CodeInterpreterMiddlewareOptions): AgentMiddleware<undefined, undefined, unknown, readonly [_$langchain.DynamicStructuredTool<z.ZodObject<{
   code: z.ZodString;
 }, z.core.$strip>, {
   code: string;
@@ -184,12 +184,35 @@ declare class ReplSession {
   private skillsFailed;
   private readonly maxPtcCalls;
   private ptcCallsRemaining;
+  /**
+   * Reset the shared WASM module. Forces the next session to instantiate
+   * a fresh module. Only needed in tests where module state must be
+   * isolated between test files.
+   *
+   * @internal
+   */
+  static resetSharedModule(): void;
   constructor(id: string, options?: ReplSessionOptions);
   private ensureStarted;
   /**
    * Load the skill into cache on first access and replay cached errors.
    */
   private ensureSkillLoaded;
+  /**
+   * Pre-load all skills referenced in source code into the in-memory
+   * cache. Must be called before `evalCodeAsync` so the module loader
+   * can resolve synchronously. An async loader would cause asyncify
+   * suspensions on each import, which is incompatible with the shared
+   * WASM module used by all sessions.
+   */
+  preloadReferencedSkills(code: string): Promise<void>;
+  /**
+   * Resolve a module specifier to source code. Strictly synchronous —
+   * only reads from the in-memory skill cache populated by
+   * `preloadReferencedSkills`. Returns error source (not a thrown
+   * exception) for missing or failed skills so QuickJS reports the
+   * error inside the VM.
+   */
   private resolveSpecifier;
   /**
    * Canonicalize an `import` specifier. Bare specifiers pass through;
@@ -199,6 +222,12 @@ declare class ReplSession {
   private normalizeSpecifier;
   /**
    * Wire the QuickJS module loader and normalizer on this session's runtime.
+   *
+   * The loader is strictly synchronous — it reads from the in-memory skill
+   * cache populated by `preloadReferencedSkills`. This is critical: an async
+   * module loader causes asyncify suspensions on each import, and disposing
+   * a runtime after multi-file imports corrupts the shared module's asyncify
+   * state, silently breaking the loader for all subsequent sessions.
    */
   private installModuleLoader;
   /**
@@ -356,5 +385,5 @@ declare function loadSkill(metadata: SkillMetadata, backend: AnyBackendProtocol)
  */
 declare function scanSkillReferences(source: string): Set<string>;
 //#endregion
-export { DEFAULT_EXECUTION_TIMEOUT, DEFAULT_MAX_PTC_CALLS, DEFAULT_MAX_STACK_SIZE, DEFAULT_MEMORY_LIMIT, type LoadedSkill, MAX_SKILL_BUNDLE_BYTES, PTCCallBudgetExceededError, type REPLMiddlewareOptions, type ReplResult, ReplSession, type ReplSessionOptions, SKILL_MODULE_EXTENSIONS, createREPLMiddleware, formatReplResult, formatSkillNotAvailable, loadSkill, scanSkillReferences, stripTypeSyntax, toCamelCase, transformForEval };
+export { type CodeInterpreterMiddlewareOptions, DEFAULT_EXECUTION_TIMEOUT, DEFAULT_MAX_PTC_CALLS, DEFAULT_MAX_STACK_SIZE, DEFAULT_MEMORY_LIMIT, type LoadedSkill, MAX_SKILL_BUNDLE_BYTES, PTCCallBudgetExceededError, type ReplResult, ReplSession, type ReplSessionOptions, SKILL_MODULE_EXTENSIONS, createCodeInterpreterMiddleware, formatReplResult, formatSkillNotAvailable, loadSkill, scanSkillReferences, stripTypeSyntax, toCamelCase, transformForEval };
 //# sourceMappingURL=index.d.cts.map

package/dist/index.d.ts

@@ -6,9 +6,9 @@ import { StructuredToolInterface } from "@langchain/core/tools";
 
 //#region src/types.d.ts
 /**
- * Configuration options for the REPL middleware.
+ * Configuration options for the Code Interpreter middleware.
  */
-interface REPLMiddlewareOptions {
+interface CodeInterpreterMiddlewareOptions {
   /**
    * Enable programmatic tool calling from within the REPL.
    *
@@ -121,9 +121,9 @@ interface SkillsContext {
 //#endregion
 //#region src/middleware.d.ts
 /**
- * Create the REPL middleware.
+ * Create the Code Interpreter middleware.
  */
-declare function createREPLMiddleware(options?: REPLMiddlewareOptions): AgentMiddleware<undefined, undefined, unknown, readonly [_$langchain.DynamicStructuredTool<z.ZodObject<{
+declare function createCodeInterpreterMiddleware(options?: CodeInterpreterMiddlewareOptions): AgentMiddleware<undefined, undefined, unknown, readonly [_$langchain.DynamicStructuredTool<z.ZodObject<{
   code: z.ZodString;
 }, z.core.$strip>, {
   code: string;
@@ -184,12 +184,35 @@ declare class ReplSession {
   private skillsFailed;
   private readonly maxPtcCalls;
   private ptcCallsRemaining;
+  /**
+   * Reset the shared WASM module. Forces the next session to instantiate
+   * a fresh module. Only needed in tests where module state must be
+   * isolated between test files.
+   *
+   * @internal
+   */
+  static resetSharedModule(): void;
   constructor(id: string, options?: ReplSessionOptions);
   private ensureStarted;
   /**
    * Load the skill into cache on first access and replay cached errors.
    */
   private ensureSkillLoaded;
+  /**
+   * Pre-load all skills referenced in source code into the in-memory
+   * cache. Must be called before `evalCodeAsync` so the module loader
+   * can resolve synchronously. An async loader would cause asyncify
+   * suspensions on each import, which is incompatible with the shared
+   * WASM module used by all sessions.
+   */
+  preloadReferencedSkills(code: string): Promise<void>;
+  /**
+   * Resolve a module specifier to source code. Strictly synchronous —
+   * only reads from the in-memory skill cache populated by
+   * `preloadReferencedSkills`. Returns error source (not a thrown
+   * exception) for missing or failed skills so QuickJS reports the
+   * error inside the VM.
+   */
   private resolveSpecifier;
   /**
    * Canonicalize an `import` specifier. Bare specifiers pass through;
@@ -199,6 +222,12 @@ declare class ReplSession {
   private normalizeSpecifier;
   /**
    * Wire the QuickJS module loader and normalizer on this session's runtime.
+   *
+   * The loader is strictly synchronous — it reads from the in-memory skill
+   * cache populated by `preloadReferencedSkills`. This is critical: an async
+   * module loader causes asyncify suspensions on each import, and disposing
+   * a runtime after multi-file imports corrupts the shared module's asyncify
+   * state, silently breaking the loader for all subsequent sessions.
    */
   private installModuleLoader;
   /**
@@ -356,5 +385,5 @@ declare function loadSkill(metadata: SkillMetadata, backend: AnyBackendProtocol)
  */
 declare function scanSkillReferences(source: string): Set<string>;
 //#endregion
-export { DEFAULT_EXECUTION_TIMEOUT, DEFAULT_MAX_PTC_CALLS, DEFAULT_MAX_STACK_SIZE, DEFAULT_MEMORY_LIMIT, type LoadedSkill, MAX_SKILL_BUNDLE_BYTES, PTCCallBudgetExceededError, type REPLMiddlewareOptions, type ReplResult, ReplSession, type ReplSessionOptions, SKILL_MODULE_EXTENSIONS, createREPLMiddleware, formatReplResult, formatSkillNotAvailable, loadSkill, scanSkillReferences, stripTypeSyntax, toCamelCase, transformForEval };
+export { type CodeInterpreterMiddlewareOptions, DEFAULT_EXECUTION_TIMEOUT, DEFAULT_MAX_PTC_CALLS, DEFAULT_MAX_STACK_SIZE, DEFAULT_MEMORY_LIMIT, type LoadedSkill, MAX_SKILL_BUNDLE_BYTES, PTCCallBudgetExceededError, type ReplResult, ReplSession, type ReplSessionOptions, SKILL_MODULE_EXTENSIONS, createCodeInterpreterMiddleware, formatReplResult, formatSkillNotAvailable, loadSkill, scanSkillReferences, stripTypeSyntax, toCamelCase, transformForEval };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -427,6 +427,38 @@ function formatSkillNotAvailable(missing) {
 	return `Skills unavailable: ${[...missing].sort().join(", ")}`;
 }
 //#endregion
+//#region src/eval-queue.ts
+/**
+* Serializes async operations on a shared WASM module.
+*
+* The quickjs-emscripten asyncify variant allows only one concurrent
+* async call per module instance. This queue enforces that constraint
+* by chaining operations into a promise queue — each caller waits for
+* the previous one to finish before executing.
+*/
+var AsyncEvalQueue = class {
+	tail = Promise.resolve();
+	/**
+	* Enqueue an async operation. The operation will not start until all
+	* previously enqueued operations have completed.
+	*/
+	async enqueue(fn) {
+		let release;
+		const gate = new Promise((r) => {
+			release = r;
+		});
+		const prev = this.tail;
+		this.tail = gate;
+		return prev.then(async () => {
+			try {
+				return await fn();
+			} finally {
+				release();
+			}
+		});
+	}
+};
+//#endregion
 //#region src/session.ts
 /**
 * Core REPL engine built on quickjs-emscripten (asyncify variant).
@@ -452,9 +484,35 @@ const DEFAULT_EXECUTION_TIMEOUT = 5e3;
 const DEFAULT_MAX_PTC_CALLS = 256;
 const DEFAULT_MAX_RESULTS_CHARS = 4e3;
 const variantImport = import("@jitl/quickjs-ng-wasmfile-release-asyncify");
-async function newAsyncModule() {
-	const variant = await variantImport;
-	return newQuickJSAsyncWASMModuleFromVariant(variant.default ?? variant);
+/**
+* Process-global eval queue. Serializes all evalCodeAsync calls across
+* sessions to enforce the asyncify one-at-a-time constraint.
+*/
+const sharedEvalQueue = new AsyncEvalQueue();
+/**
+* Process-global WASM module shared by all sessions.
+*
+* Each session creates its own runtime and context on this module,
+* providing full isolation for globals, heap, and stack. The module
+* itself is stateless between runtimes — only the compiled WASM code
+* and Emscripten infrastructure are shared.
+*
+* This is safe because:
+* - The module loader is synchronous (preloaded skill cache), so
+*   imports don't cause asyncify suspensions.
+* - Tool injection uses the promise-based pattern (newFunction +
+*   newPromise), not newAsyncifiedFunction, so tool calls don't
+*   cause asyncify suspensions.
+* - The eval queue serializes evalCodeAsync calls to satisfy the
+*   one-concurrent-async-call-per-module constraint.
+*/
+let sharedModulePromise;
+function getSharedModule() {
+	if (!sharedModulePromise) sharedModulePromise = (async () => {
+		const variant = await variantImport;
+		return newQuickJSAsyncWASMModuleFromVariant(variant.default ?? variant);
+	})();
+	return sharedModulePromise;
 }
 function makeErrorSource(message) {
 	return `throw { name: "Error", message: ${JSON.stringify(message)} };`;
@@ -575,6 +633,16 @@ var ReplSession = class ReplSession {
 	skillsFailed = /* @__PURE__ */ new Map();
 	maxPtcCalls;
 	ptcCallsRemaining = null;
+	/**
+	* Reset the shared WASM module. Forces the next session to instantiate
+	* a fresh module. Only needed in tests where module state must be
+	* isolated between test files.
+	*
+	* @internal
+	*/
+	static resetSharedModule() {
+		sharedModulePromise = void 0;
+	}
 	constructor(id, options = {}) {
 		this.id = id;
 		this.options = options;
@@ -583,7 +651,7 @@ var ReplSession = class ReplSession {
 	async ensureStarted() {
 		if (this.runtime) return;
 		const { memoryLimitBytes = DEFAULT_MEMORY_LIMIT, maxStackSizeBytes = DEFAULT_MAX_STACK_SIZE, tools, skillsEnabled = false, maxResultChars = DEFAULT_MAX_RESULTS_CHARS, captureConsole = true } = this.options;
-		const runtime = (await newAsyncModule()).newRuntime();
+		const runtime = (await getSharedModule()).newRuntime();
 		runtime.setMemoryLimit(memoryLimitBytes);
 		runtime.setMaxStackSize(maxStackSizeBytes);
 		const context = runtime.newContext();
@@ -615,21 +683,45 @@ var ReplSession = class ReplSession {
 			throw err;
 		}
 	}
-	async resolveSpecifier(specifier) {
+	/**
+	* Pre-load all skills referenced in source code into the in-memory
+	* cache. Must be called before `evalCodeAsync` so the module loader
+	* can resolve synchronously. An async loader would cause asyncify
+	* suspensions on each import, which is incompatible with the shared
+	* WASM module used by all sessions.
+	*/
+	async preloadReferencedSkills(code) {
+		const refs = scanSkillReferences(code);
+		for (const name of refs) {
+			if (this.skillsLoaded.has(name) || this.skillsFailed.has(name)) continue;
+			try {
+				await this.ensureSkillLoaded(name);
+			} catch (err) {
+				if (!this.skillsFailed.has(name)) this.skillsFailed.set(name, err);
+			}
+		}
+	}
+	/**
+	* Resolve a module specifier to source code. Strictly synchronous —
+	* only reads from the in-memory skill cache populated by
+	* `preloadReferencedSkills`. Returns error source (not a thrown
+	* exception) for missing or failed skills so QuickJS reports the
+	* error inside the VM.
+	*/
+	resolveSpecifier(specifier) {
 		const parsed = parseSkillSpecifier(specifier);
 		if (parsed === void 0) return makeErrorSource(`Module not found: ${specifier}`);
-		let loaded;
-		try {
-			loaded = await this.ensureSkillLoaded(parsed.name);
-		} catch (err) {
-			return makeErrorSource(err.message ?? String(err));
-		}
+		const cachedError = this.skillsFailed.get(parsed.name);
+		if (cachedError !== void 0) return makeErrorSource(cachedError.message ?? String(cachedError));
+		const loaded = this.skillsLoaded.get(parsed.name);
+		if (loaded === void 0) return makeErrorSource(`Skill '${parsed.name}' was not preloaded. Ensure the import specifier is a static string literal (dynamic specifiers like \`import("@/skills/" + name)\` are not supported).`);
 		if (parsed.rel === void 0) {
 			const source = loaded.files.get(loaded.entryRel);
 			if (source === void 0) return makeErrorSource(`Skill '${parsed.name}': entrypoint '${loaded.entryRel}' missing from bundle`);
 			return source;
 		}
-		const source = loaded.files.get(parsed.rel);
+		let source = loaded.files.get(parsed.rel);
+		if (source === void 0 && parsed.rel.endsWith(".js")) source = loaded.files.get(parsed.rel.slice(0, -3) + ".ts");
 		if (source === void 0) return makeErrorSource(`Skill '${parsed.name}': '${parsed.rel}' not found in bundle`);
 		return source;
 	}
@@ -649,10 +741,16 @@ var ReplSession = class ReplSession {
 	}
 	/**
 	* Wire the QuickJS module loader and normalizer on this session's runtime.
+	*
+	* The loader is strictly synchronous — it reads from the in-memory skill
+	* cache populated by `preloadReferencedSkills`. This is critical: an async
+	* module loader causes asyncify suspensions on each import, and disposing
+	* a runtime after multi-file imports corrupts the shared module's asyncify
+	* state, silently breaking the loader for all subsequent sessions.
 	*/
 	installModuleLoader() {
 		if (this.runtime === null) return;
-		this.runtime.setModuleLoader(async (specifier) => this.resolveSpecifier(specifier), (base, requested) => this.normalizeSpecifier(base, requested));
+		this.runtime.setModuleLoader((specifier) => this.resolveSpecifier(specifier), (base, requested) => this.normalizeSpecifier(base, requested));
 	}
 	/**
 	* Initialise the per-eval PTC counter. Called at the top of every `eval()`.
@@ -735,6 +833,7 @@ var ReplSession = class ReplSession {
 		await this.ensureStarted();
 		const runtime = this.runtime;
 		const context = this.context;
+		await this.preloadReferencedSkills(code);
 		const drainLogs = () => {
 			const [raw, dropped] = this.consoleBuffer.drain();
 			return {
@@ -747,7 +846,7 @@ var ReplSession = class ReplSession {
 			if (timeoutMs >= 0) runtime.setInterruptHandler(shouldInterruptAfterDeadline(Date.now() + timeoutMs));
 			else runtime.setInterruptHandler(() => false);
 			const transformed = transformForEval(code);
-			const result = await context.evalCodeAsync(transformed);
+			const result = await sharedEvalQueue.enqueue(() => context.evalCodeAsync(transformed));
 			if (result.error) {
 				const error = context.dump(result.error);
 				result.error.dispose();
@@ -906,7 +1005,7 @@ var ReplSession = class ReplSession {
 //#endregion
 //#region src/middleware.ts
 /**
-* REPL middleware for deepagents.
+* Code Interpreter middleware for deepagents.
 *
 * Provides an `eval` tool that runs JavaScript in a WASM-sandboxed QuickJS
 * interpreter. Supports:
@@ -1002,9 +1101,9 @@ async function prepareSkillsForEval(session, skillsBackend, code) {
 	});
 }
 /**
-* Create the REPL middleware.
+* Create the Code Interpreter middleware.
 */
-function createREPLMiddleware(options = {}) {
+function createCodeInterpreterMiddleware(options = {}) {
 	const { ptc, memoryLimitBytes = DEFAULT_MEMORY_LIMIT, maxStackSizeBytes = DEFAULT_MAX_STACK_SIZE, executionTimeoutMs = DEFAULT_EXECUTION_TIMEOUT, systemPrompt: customSystemPrompt = null, skillsBackend, maxPtcCalls = 256, maxResultChars = DEFAULT_MAX_RESULTS_CHARS, toolName = DEFAULT_TOOL_NAME, captureConsole = true } = options;
 	if (maxPtcCalls !== null && maxPtcCalls !== void 0 && maxPtcCalls < 1) throw new Error("`maxPtcCalls` must be >= 1 or null");
 	const baseSystemPrompt = customSystemPrompt || renderReplSystemPrompt({
@@ -1020,7 +1119,7 @@ function createREPLMiddleware(options = {}) {
 		return resolveToolList(ptc, allTools.filter((t) => t.name !== toolName));
 	}
 	return createMiddleware({
-		name: "REPLMiddleware",
+		name: "CodeInterpreterMiddleware",
 		tools: [tool(async (input, config) => {
 			const sessionKey = `${config.configurable?.thread_id || "__default__"}:${middlewareId}`;
 			const session = ReplSession.getOrCreate(sessionKey, {
@@ -1064,6 +1163,6 @@ function createREPLMiddleware(options = {}) {
 	});
 }
 //#endregion
-export { DEFAULT_EXECUTION_TIMEOUT, DEFAULT_MAX_PTC_CALLS, DEFAULT_MAX_STACK_SIZE, DEFAULT_MEMORY_LIMIT, MAX_SKILL_BUNDLE_BYTES, PTCCallBudgetExceededError, ReplSession, SKILL_MODULE_EXTENSIONS, createREPLMiddleware, formatReplResult, formatSkillNotAvailable, loadSkill, scanSkillReferences, stripTypeSyntax, toCamelCase, transformForEval };
+export { DEFAULT_EXECUTION_TIMEOUT, DEFAULT_MAX_PTC_CALLS, DEFAULT_MAX_STACK_SIZE, DEFAULT_MEMORY_LIMIT, MAX_SKILL_BUNDLE_BYTES, PTCCallBudgetExceededError, ReplSession, SKILL_MODULE_EXTENSIONS, createCodeInterpreterMiddleware, formatReplResult, formatSkillNotAvailable, loadSkill, scanSkillReferences, stripTypeSyntax, toCamelCase, transformForEval };
 
 //# sourceMappingURL=index.js.map