@langchain/quickjs 0.2.6 → 0.4.0

package/dist/index.d.ts

@@ -6,9 +6,9 @@ import { StructuredToolInterface } from "@langchain/core/tools";
 
 //#region src/types.d.ts
 /**
- * Configuration options for the QuickJS REPL middleware.
+ * Configuration options for the Code Interpreter middleware.
  */
-interface QuickJSMiddlewareOptions {
+interface CodeInterpreterMiddlewareOptions {
   /**
    * Enable programmatic tool calling from within the REPL.
    *
@@ -20,7 +20,7 @@ interface QuickJSMiddlewareOptions {
   ptc?: (string | StructuredToolInterface)[];
   /**
    * Memory limit in bytes.
-   * @default 52428800 (50MB)
+   * @default 67108864 (64MB)
    */
   memoryLimitBytes?: number;
   /**
@@ -31,7 +31,7 @@ interface QuickJSMiddlewareOptions {
   /**
    * Execution timeout in milliseconds per evaluation.
    * Set to a negative value to disable the timeout entirely.
-   * @default 30000 (30s)
+   * @default 5000 (5s)
    */
   executionTimeoutMs?: number;
   /**
@@ -66,6 +66,18 @@ interface QuickJSMiddlewareOptions {
    * @default 4000
    */
   maxResultChars?: number;
+  /**
+   * Name of the tool exposed to the model.
+   * @default "eval"
+   */
+  toolName?: string;
+  /**
+   * If true, install a `console` object that buffers `console.log/warn/error`
+   * calls and emits them alongside the result. If false, console output is
+   * silently discarded.
+   * @default true
+   */
+  captureConsole?: boolean;
 }
 /**
  * Options for creating a ReplSession.
@@ -77,6 +89,7 @@ interface ReplSessionOptions {
   skillsEnabled?: boolean;
   maxPtcCalls?: number | null;
   maxResultChars?: number;
+  captureConsole?: boolean;
 }
 /**
  * Result of a single REPL evaluation.
@@ -108,15 +121,15 @@ interface SkillsContext {
 //#endregion
 //#region src/middleware.d.ts
 /**
- * Create the QuickJS REPL middleware.
+ * Create the Code Interpreter middleware.
  */
-declare function createQuickJSMiddleware(options?: QuickJSMiddlewareOptions): 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;
 }, {
   code: string;
-}, string, unknown, "js_eval">]>;
+}, string, unknown, string>]>;
 //#endregion
 //#region src/errors.d.ts
 /**
@@ -149,7 +162,7 @@ declare class PTCCallBudgetExceededError extends Error {
 //#region src/session.d.ts
 declare const DEFAULT_MEMORY_LIMIT: number;
 declare const DEFAULT_MAX_STACK_SIZE: number;
-declare const DEFAULT_EXECUTION_TIMEOUT = 30000;
+declare const DEFAULT_EXECUTION_TIMEOUT = 5000;
 declare const DEFAULT_MAX_PTC_CALLS = 256;
 /**
  * Sandboxed JavaScript REPL session backed by QuickJS WASM.
@@ -171,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;
@@ -186,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;
   /**
@@ -221,7 +263,7 @@ declare class ReplSession {
   static deleteSession(key: string): void;
   /**
    * Push the current skills metadata + backend into the session.
-   * Called by the middleware once per `js_eval` invocation, before eval runs.
+   * Called by the middleware once per `eval` invocation, before eval runs.
    * Pass `undefined` to clear the context (no skill imports will resolve).
    */
   setSkillsContext(ctx?: SkillsContext): void;
@@ -343,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 QuickJSMiddlewareOptions, type ReplResult, ReplSession, type ReplSessionOptions, SKILL_MODULE_EXTENSIONS, createQuickJSMiddleware, 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).
@@ -446,15 +478,41 @@ function formatSkillNotAvailable(missing) {
 * runtime is lazily started on the first `.eval()` call, making the session
 * safe across graph interrupts and checkpointing.
 */
-const DEFAULT_MEMORY_LIMIT = 50 * 1024 * 1024;
+const DEFAULT_MEMORY_LIMIT = 64 * 1024 * 1024;
 const DEFAULT_MAX_STACK_SIZE = 320 * 1024;
-const DEFAULT_EXECUTION_TIMEOUT = 3e4;
+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;
@@ -582,15 +650,15 @@ 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 } = this.options;
-		const runtime = (await newAsyncModule()).newRuntime();
+		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 getSharedModule()).newRuntime();
 		runtime.setMemoryLimit(memoryLimitBytes);
 		runtime.setMaxStackSize(maxStackSizeBytes);
 		const context = runtime.newContext();
 		this.runtime = runtime;
 		this.context = context;
 		this.consoleBuffer = new ConsoleBuffer(maxResultChars);
-		this.setupConsole();
+		if (captureConsole) this.setupConsole();
 		if (tools !== void 0 && tools.length > 0) this.injectTools(tools);
 		if (skillsEnabled) this.installModuleLoader();
 	}
@@ -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()`.
@@ -716,7 +814,7 @@ var ReplSession = class ReplSession {
 	}
 	/**
 	* Push the current skills metadata + backend into the session.
-	* Called by the middleware once per `js_eval` invocation, before eval runs.
+	* Called by the middleware once per `eval` invocation, before eval runs.
 	* Pass `undefined` to clear the context (no skill imports will resolve).
 	*/
 	setSkillsContext(ctx) {
@@ -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,33 +1005,26 @@ var ReplSession = class ReplSession {
 //#endregion
 //#region src/middleware.ts
 /**
-* QuickJS REPL middleware for deepagents.
+* Code Interpreter middleware for deepagents.
 *
-* Provides a `js_eval` tool that runs JavaScript in a WASM-sandboxed QuickJS
+* Provides an `eval` tool that runs JavaScript in a WASM-sandboxed QuickJS
 * interpreter. Supports:
 * - Persistent state across evaluations (true REPL)
 * - Programmatic tool calling (PTC) — expose agent or custom tools inside the REPL
 */
-const REPL_SYSTEM_PROMPT = dedent`
-  ## TypeScript/JavaScript REPL (\`js_eval\`)
-
-  You have access to a sandboxed TypeScript/JavaScript REPL running in an isolated interpreter.
-  TypeScript syntax (type annotations, interfaces, generics, \`as\` casts) is supported and stripped at evaluation time.
-  Variables, functions, and closures persist across calls within the same session.
-
-  ### Hard rules
-
-  - **No network, no direct filesystem** — only through tools provided in the \`tools\` namespace below.
-  - **Cite your sources** — when reporting values from files, include the path and key/index so the user can verify.
-  - **Use console.log()** for output — it is captured and returned. \`console.warn()\` and \`console.error()\` are also available.
-  - **Reuse state from previous cells** — variables, functions, and results from earlier \`js_eval\` calls persist across calls. Reference them by name in follow-up cells instead of re-embedding data as inline JSON literals.
-
-  ### Limitations
+const DEFAULT_TOOL_NAME = "eval";
+function renderReplSystemPrompt(opts) {
+	return dedent`
+    ### Interpreter
 
-  - ES2023+ syntax with TypeScript support. No Node.js APIs, no \`require\`, no \`import\`.
-  - Output is truncated beyond a fixed character limit — be selective about what you log.
-  - Execution timeout per call (default 30 s).
-`;
+    An \`${opts.toolName}\` tool is available. It runs JavaScript in a persistent REPL.
+    - State (variables, functions) persists across tool calls within a single turn of conversation. They DO NOT persist across multiple turns.
+    - Top-level \`await\` works; Promises resolve before the call returns.
+    - Sandboxed: no filesystem, no stdlib, no network, no real clock, no \`fetch\`, no \`require\`.
+    - Timeout: ${opts.timeout}s per call. Memory: ${opts.memoryLimitMb} MB total.
+    - \`console.log\` output is captured and returned alongside the result.
+  `;
+}
 /**
 * Generate the PTC API Reference section for the system prompt.
 */
@@ -1009,21 +1101,25 @@ async function prepareSkillsForEval(session, skillsBackend, code) {
 	});
 }
 /**
-* Create the QuickJS REPL middleware.
+* Create the Code Interpreter middleware.
 */
-function createQuickJSMiddleware(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 } = 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 || REPL_SYSTEM_PROMPT;
+	const baseSystemPrompt = customSystemPrompt || renderReplSystemPrompt({
+		toolName,
+		timeout: executionTimeoutMs / 1e3,
+		memoryLimitMb: Math.floor(memoryLimitBytes / (1024 * 1024))
+	});
 	const middlewareId = crypto.randomUUID();
 	let cachedPtcPrompt = null;
 	let ptcTools = [];
 	function filterToolsForPtc(allTools) {
 		if (!ptc) return [];
-		return resolveToolList(ptc, allTools.filter((t) => t.name !== "js_eval"));
+		return resolveToolList(ptc, allTools.filter((t) => t.name !== toolName));
 	}
 	return createMiddleware({
-		name: "QuickJSMiddleware",
+		name: "CodeInterpreterMiddleware",
 		tools: [tool(async (input, config) => {
 			const sessionKey = `${config.configurable?.thread_id || "__default__"}:${middlewareId}`;
 			const session = ReplSession.getOrCreate(sessionKey, {
@@ -1032,7 +1128,8 @@ function createQuickJSMiddleware(options = {}) {
 				maxPtcCalls,
 				tools: ptcTools,
 				skillsEnabled: skillsBackend !== void 0,
-				maxResultChars
+				maxResultChars,
+				captureConsole
 			});
 			if (skillsBackend !== void 0) {
 				const setupError = await prepareSkillsForEval(session, skillsBackend, input.code);
@@ -1040,7 +1137,7 @@ function createQuickJSMiddleware(options = {}) {
 			}
 			return formatReplResult(await session.eval(input.code, executionTimeoutMs));
 		}, {
-			name: "js_eval",
+			name: toolName,
 			description: dedent`
         Evaluate TypeScript/JavaScript code in a sandboxed REPL. State persists across calls.
         Use console.log() for output. Returns the result of the last expression.
@@ -1066,6 +1163,6 @@ function createQuickJSMiddleware(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, createQuickJSMiddleware, 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