@langchain/quickjs 0.2.5 → 0.3.0

package/dist/index.js

@@ -1,79 +1,17 @@
 import { createMiddleware, tool } from "langchain";
 import { z } from "zod/v4";
-import { StateBackend, adaptBackendProtocol, resolveBackend } from "deepagents";
 import dedent from "dedent";
+import { getCurrentTaskInput } from "@langchain/langgraph";
+import { adaptBackendProtocol, resolveBackend } from "deepagents";
 import { shouldInterruptAfterDeadline } from "quickjs-emscripten";
 import { newQuickJSAsyncWASMModuleFromVariant } from "quickjs-emscripten-core";
-import { compile } from "json-schema-to-typescript";
-import { toJsonSchema } from "@langchain/core/utils/json_schema";
+import * as posix from "node:path/posix";
 import { Parser } from "acorn";
 import { tsPlugin } from "@sveltejs/acorn-typescript";
 import { walk } from "estree-walker";
 import MagicString from "magic-string";
-import { getCurrentTaskInput } from "@langchain/langgraph";
-//#region src/utils.ts
-/**
-* Convert a snake_case or kebab-case string to camelCase.
-*/
-function toCamelCase(name) {
-	return name.replace(/[-_]([a-z])/g, (_, c) => c.toUpperCase());
-}
-/**
-* Format the result of a REPL evaluation for the agent.
-*/
-function formatReplResult(result) {
-	const parts = [];
-	if (result.logs.length > 0) parts.push(result.logs.join("\n"));
-	if (result.ok) {
-		if (result.value !== void 0) {
-			const formatted = typeof result.value === "string" ? result.value : JSON.stringify(result.value, null, 2);
-			parts.push(`→ ${formatted}`);
-		}
-	} else if (result.error) {
-		const errName = result.error.name || "Error";
-		const errMsg = result.error.message || "Unknown error";
-		parts.push(`${errName}: ${errMsg}`);
-		if (result.error.stack) parts.push(result.error.stack);
-	}
-	return parts.join("\n") || "(no output)";
-}
-function safeToJsonSchema(schema) {
-	try {
-		return toJsonSchema(schema);
-	} catch {
-		return;
-	}
-}
-async function schemaToInterface(jsonSchema, interfaceName) {
-	return (await compile({
-		...jsonSchema,
-		additionalProperties: false
-	}, interfaceName, {
-		bannerComment: "",
-		additionalProperties: false
-	})).replace(/^export /, "").trimEnd();
-}
-function capitalize(s) {
-	return s.charAt(0).toUpperCase() + s.slice(1);
-}
-async function toolToTypeSignature(name, description, jsonSchema) {
-	const inputType = `${capitalize(name)}Input`;
-	if (!jsonSchema || !jsonSchema.properties) return dedent`
-      /**
-       * ${description}
-       */
-      async tools.${name}(input: Record<string, unknown>): Promise<string>
-    `;
-	return dedent`
-    ${await schemaToInterface(jsonSchema, inputType)}
-
-    /**
-     * ${description}
-     */
-    async tools.${name}(input: ${inputType}): Promise<string>
-  `;
-}
-//#endregion
+import { compile } from "json-schema-to-typescript";
+import { toJsonSchema } from "@langchain/core/utils/json_schema";
 //#region src/transform.ts
 /**
 * AST-based code transform pipeline for the REPL.
@@ -234,6 +172,260 @@ function findLastNonEmptyNode(nodes, s) {
 function isExpression(node) {
 	return node.type === "ExpressionStatement";
 }
+/**
+* Strip TypeScript type syntax from an ES-module source so QuickJS can
+* evaluate it as a standard JS module.
+*
+* Unlike `transformForEval`, this keeps `import`/`export` declarations,
+* does not hoist to `globalThis`, and does not wrap in an IIFE.
+* On parse failure the original source is returned unchanged.
+*/
+function stripTypeSyntax(code) {
+	let ast;
+	try {
+		ast = TSParser.parse(code, {
+			ecmaVersion: "latest",
+			sourceType: "module",
+			locations: true
+		});
+	} catch {
+		return code;
+	}
+	const magicString = new MagicString(code);
+	const program = ast;
+	for (const node of program.body) {
+		if (isTSOnlyNode(node)) {
+			magicString.remove(node.start, node.end);
+			continue;
+		}
+		walk(node, { enter(n) {
+			stripTypeAnnotationFromNode(magicString, n);
+		} });
+	}
+	return magicString.toString();
+}
+//#endregion
+//#region src/skills.ts
+/**
+* File extensions the loader will enumerate from a skill directory.
+*/
+const SKILL_MODULE_EXTENSIONS = [
+	".js",
+	".mjs",
+	".cjs",
+	".ts",
+	".mts",
+	".cts",
+	".jsx",
+	".tsx"
+];
+/**
+* Hard cap on total bytes pulled for one skill's bundle (1 MiB).
+*/
+const MAX_SKILL_BUNDLE_BYTES = 1 * 1024 * 1024;
+/**
+* Validates a skill name against the spec's kebab-case rule.
+*/
+const SKILL_NAME_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/**
+* Matches `"@/skills/<name>"` or `'@/skills/<name>'` references in source.
+* Template literals and computed specifiers are not caught.
+*/
+const SKILL_SPECIFIER_RE = /["']@\/skills\/([a-z0-9]+(?:-[a-z0-9]+)*)["']/g;
+/**
+* List every code-extension file under `skillDir` (recursive).
+*/
+async function enumerateCodeFiles(backend, skillDir, skillName) {
+	const seen = /* @__PURE__ */ new Set();
+	for (const ext of SKILL_MODULE_EXTENSIONS) {
+		const result = await backend.glob(`**/*${ext}`, skillDir);
+		if (result.error !== void 0) throw new Error(`Skill '${skillName}': failed to list '${skillDir}': ${result.error}`);
+		const matches = result.files ?? [];
+		for (const match of matches) seen.add(match.path);
+	}
+	return [...seen].sort();
+}
+/**
+* Decode download responses into [path, source] pairs.
+*/
+function decodeFiles(responses, skillName) {
+	const decoder = new TextDecoder("utf-8", { fatal: true });
+	const pairs = [];
+	for (const response of responses) {
+		if (response.error !== null || response.content === null) throw new Error(`Skill '${skillName}': failed to download '${response.path}': ${response.error ?? "no content"}`);
+		let source;
+		try {
+			source = decoder.decode(response.content);
+		} catch {
+			throw new Error(`Skill '${skillName}': file '${response.path}' is not valid UTF-8`);
+		}
+		pairs.push([response.path, source]);
+	}
+	return pairs;
+}
+/**
+* Throws an Error when the total decoded size of all files exceeds
+* `MAX_SKILL_BUNDLE_BYTES`. Counts characters rather than bytes, which
+* over-counts multi-byte UTF-8. Intentionally errs toward rejection.
+*/
+function validateBundleSize(pairs, skillName) {
+	let total = 0;
+	for (const [, source] of pairs) total += source.length;
+	if (total > 1048576) throw new Error(`Skill '${skillName}': bundle exceeds ${MAX_SKILL_BUNDLE_BYTES} bytes (total ${total})`);
+}
+/**
+* Express `absolutePath` as a POSIX-relative path under `skillDir`.
+* Throws an Error if the path escapes the skill directory which indicates
+* a backend bug, not a user error.
+*/
+function relativeUnder(skillDir, absolutePath, skillName) {
+	const rel = posix.relative(skillDir, absolutePath);
+	if (rel === "" || rel.startsWith("..")) throw new Error(`Skill '${skillName}': file ${absolutePath} is not under '${skillDir}'`);
+	return rel;
+}
+/**
+* Build the relative-path → source map, applying `stripTypeSyntax` to each file.
+*/
+function buildFilesMap(skillDir, entryRel, pairs, skillName) {
+	const files = /* @__PURE__ */ new Map();
+	let entryPresent = false;
+	for (const [absPath, source] of pairs) {
+		const rel = relativeUnder(skillDir, absPath, skillName);
+		files.set(rel, stripTypeSyntax(source));
+		if (rel === entryRel) entryPresent = true;
+	}
+	if (!entryPresent) throw new Error(`Skill '${skillName}': module path '${entryRel}' did not match any file in the skill directory`);
+	return files;
+}
+/**
+* Build a `LoadedSkill` from a skill's metadata and a backend handle.
+*
+* Enumerates code files under the skill directory, downloads them,
+* strips TypeScript syntax, and validates the entrypoint is present.
+*/
+async function loadSkill(metadata, backend) {
+	const name = metadata.name;
+	if (!SKILL_NAME_RE.test(name)) throw new Error(`Skill name '${name}' is not a valid kebab-case identifier`);
+	const entryRel = metadata.module;
+	if (entryRel === void 0 || entryRel === "") throw new Error(`Skill '${name}' has no 'module' frontmatter key - only skills with a declared entrypoint are installable`);
+	const adapted = adaptBackendProtocol(backend);
+	if (adapted.downloadFiles === void 0) throw new Error(`Skill '${name}': backend does not implement downloadFiles`);
+	const skillDir = posix.dirname(metadata.path);
+	const codeFiles = await enumerateCodeFiles(adapted, skillDir, name);
+	if (codeFiles.length === 0) throw new Error(`Skill '${name}': no JS/TS files under '${skillDir}'`);
+	const filePairs = decodeFiles(await adapted.downloadFiles(codeFiles), name);
+	validateBundleSize(filePairs, name);
+	const files = buildFilesMap(skillDir, entryRel, filePairs, name);
+	return {
+		name,
+		specifier: `@/skills/${name}`,
+		entryRel,
+		files
+	};
+}
+/**
+* Extract skill names referenced by `"@/skills/<name>"` literals in source.
+*
+* Used as a pre-eval scan so the middleware can surface `SkillNotAvailable`
+* before evaluation starts. Dynamic imports with computed specifiers are
+* not detected.
+*/
+function scanSkillReferences(source) {
+	const names = /* @__PURE__ */ new Set();
+	const matches = source.matchAll(SKILL_SPECIFIER_RE);
+	for (const match of matches) names.add(match[1]);
+	return names;
+}
+//#endregion
+//#region src/errors.ts
+/**
+* Thrown when a single eval exhausts its configured PTC call budget.
+*/
+var PTCCallBudgetExceededError = class extends Error {
+	limit;
+	attempted;
+	functionName;
+	constructor(options) {
+		super(`PTC call budget exceeded (limit=${options.limit}, attempted=${options.attempted}, function=${options.functionName})`);
+		this.name = "PTCCallBudgetExceededError";
+		this.limit = options.limit;
+		this.attempted = options.attempted;
+		this.functionName = options.functionName;
+	}
+};
+//#endregion
+//#region src/utils.ts
+/**
+* Convert a snake_case or kebab-case string to camelCase.
+*/
+function toCamelCase(name) {
+	return name.replace(/[-_]([a-z])/g, (_, c) => c.toUpperCase());
+}
+/**
+* Format the result of a REPL evaluation for the agent.
+*/
+function formatReplResult(result) {
+	const parts = [];
+	if (result.logs.length > 0) {
+		let logsText = result.logs.join("\n");
+		if (result.logsDroppedChars > 0) logsText += `\n[truncated ${result.logsDroppedChars} chars]`;
+		parts.push(logsText);
+	}
+	if (result.ok) {
+		if (result.value !== void 0) {
+			const formatted = typeof result.value === "string" ? result.value : JSON.stringify(result.value, null, 2);
+			parts.push(`→ ${formatted}`);
+		}
+	} else if (result.error) {
+		const errName = result.error.name || "Error";
+		const errMsg = result.error.message || "Unknown error";
+		parts.push(`${errName}: ${errMsg}`);
+		if (result.error.stack) parts.push(result.error.stack);
+	}
+	return parts.join("\n") || "(no output)";
+}
+function safeToJsonSchema(schema) {
+	try {
+		return toJsonSchema(schema);
+	} catch {
+		return;
+	}
+}
+async function schemaToInterface(jsonSchema, interfaceName) {
+	return (await compile({
+		...jsonSchema,
+		additionalProperties: false
+	}, interfaceName, {
+		bannerComment: "",
+		additionalProperties: false
+	})).replace(/^export /, "").trimEnd();
+}
+function capitalize(s) {
+	return s.charAt(0).toUpperCase() + s.slice(1);
+}
+async function toolToTypeSignature(name, description, jsonSchema) {
+	const inputType = `${capitalize(name)}Input`;
+	if (!jsonSchema || !jsonSchema.properties) return dedent`
+      /**
+       * ${description}
+       */
+      async tools.${name}(input: Record<string, unknown>): Promise<string>
+    `;
+	return dedent`
+    ${await schemaToInterface(jsonSchema, inputType)}
+
+    /**
+     * ${description}
+     */
+    async tools.${name}(input: ${inputType}): Promise<string>
+  `;
+}
+/**
+* Render a pre-eval error when referenced skills are not available on the agent.
+*/
+function formatSkillNotAvailable(missing) {
+	return `Skills unavailable: ${[...missing].sort().join(", ")}`;
+}
 //#endregion
 //#region src/session.ts
 /**
@@ -253,65 +445,237 @@ function isExpression(node) {
 * It holds an `id` that keys into a static session map. The heavy QuickJS
 * runtime is lazily started on the first `.eval()` call, making the session
 * safe across graph interrupts and checkpointing.
-*
-* File writes inside the REPL are buffered (`pendingWrites`) and only
-* flushed to the backend after a script finishes executing. Call
-* `session.flushWrites(backend)` after eval to persist them.
 */
-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;
-let asyncModulePromise;
-async function getAsyncModule() {
-	if (!asyncModulePromise) asyncModulePromise = (async () => {
-		const variant = await import("@jitl/quickjs-ng-wasmfile-release-asyncify");
-		return newQuickJSAsyncWASMModuleFromVariant(variant.default ?? variant);
-	})();
-	return asyncModulePromise;
+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);
+}
+function makeErrorSource(message) {
+	return `throw { name: "Error", message: ${JSON.stringify(message)} };`;
 }
 /**
+* Parse a canonicalized skill specifier into `{ name, rel }`.
+* Returns `undefined` for anything that isn't a valid `@/skills/<name>` or
+* `@/skills/<name>/<rel>` shape. `rel` is absent for the bare form.
+*/
+function parseSkillSpecifier(specifier) {
+	if (!specifier.startsWith("@/skills/")) return;
+	const tail = specifier.slice(9);
+	const slashIdx = tail.indexOf("/");
+	const name = slashIdx === -1 ? tail : tail.slice(0, slashIdx);
+	if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name)) return;
+	const rel = slashIdx === -1 ? void 0 : tail.slice(slashIdx + 1);
+	if (rel !== void 0 && rel === "") return;
+	return {
+		name,
+		rel
+	};
+}
+/**
+* Return the `@/skills/<name>` prefix for the skill that owns `base`, or `undefined`.
+*/
+function matchSkillPrefix(base) {
+	const parsed = parseSkillSpecifier(base);
+	if (parsed === void 0) return;
+	return `@/skills/${parsed.name}`;
+}
+/**
+* Return the directory portion of a slash-separated specifier path.
+*/
+function posixDirname(p) {
+	const idx = p.lastIndexOf("/");
+	if (idx === -1) return "";
+	return p.slice(0, idx);
+}
+/**
+* POSIX join for slash-separated specifiers. Avoids `node:path/posix`
+* since session.ts is consumed in browser bundles.
+*/
+function posixJoin(base, rel) {
+	const out = [];
+	const segments = `${base}/${rel}`.split("/");
+	for (const segment of segments) {
+		if (segment === "" || segment === ".") continue;
+		if (segment === "..") {
+			out.pop();
+			continue;
+		}
+		out.push(segment);
+	}
+	return out.join("/");
+}
+/**
+* Fixed-size character buffer for capturing console output from the QuickJS VM.
+*
+* Lines are accumulated up to `maxChars`. Once the cap is reached, excess
+* characters are counted as dropped rather than silently discarded without
+* attribution, so callers can surface a truncation notice to the user.
+*/
+var ConsoleBuffer = class {
+	maxChars;
+	buffer = "";
+	droppedChars = 0;
+	constructor(maxChars) {
+		this.maxChars = Math.max(maxChars, 0);
+	}
+	/**
+	* Append `line` to the buffer.
+	*
+	* If the buffer is already full the entire line is counted as dropped.
+	* If `line` partially fits, the fitting prefix is stored and the remainder
+	* is counted as dropped.
+	*/
+	append(line) {
+		const remaining = this.maxChars - this.buffer.length;
+		if (remaining <= 0) {
+			this.droppedChars += line.length;
+			return;
+		}
+		if (line.length <= remaining) this.buffer += line;
+		else {
+			this.buffer += line.slice(0, remaining);
+			this.droppedChars += line.length - remaining;
+		}
+	}
+	/**
+	* Return the buffered output and dropped-character count as `[buffered,
+	* droppedChars]`, then reset both to zero.
+	*/
+	drain() {
+		const out = this.buffer;
+		const dropped = this.droppedChars;
+		this.buffer = "";
+		this.droppedChars = 0;
+		return [out, dropped];
+	}
+};
+/**
 * Sandboxed JavaScript REPL session backed by QuickJS WASM.
 *
 * Serializable — holds an `id` that keys into a static session map.
 * The QuickJS runtime is lazily started on the first `.eval()` call
 * and reconnected if a session with the same id already exists.
 * This makes it safe to store in LangGraph state across interrupts.
-*
-* File writes are buffered during execution and flushed via
-* `flushWrites(backend)` after eval completes.
 */
 var ReplSession = class ReplSession {
 	static sessions = /* @__PURE__ */ new Map();
 	id;
-	pendingWrites = [];
 	runtime = null;
 	context = null;
-	logs = [];
-	_options;
-	_backend = null;
+	consoleBuffer = new ConsoleBuffer(DEFAULT_MAX_RESULTS_CHARS);
+	options;
+	skillsContext;
+	skillsLoaded = /* @__PURE__ */ new Map();
+	skillsFailed = /* @__PURE__ */ new Map();
+	maxPtcCalls;
+	ptcCallsRemaining = null;
 	constructor(id, options = {}) {
 		this.id = id;
-		this._options = options;
-	}
-	get backend() {
-		return this._backend;
-	}
-	set backend(b) {
-		this._backend = b ? adaptBackendProtocol(b) : null;
+		this.options = options;
+		this.maxPtcCalls = options.maxPtcCalls !== void 0 ? options.maxPtcCalls : 256;
 	}
 	async ensureStarted() {
 		if (this.runtime) return;
-		const { memoryLimitBytes = DEFAULT_MEMORY_LIMIT, maxStackSizeBytes = DEFAULT_MAX_STACK_SIZE, backend, tools } = this._options;
-		const runtime = (await getAsyncModule()).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 newAsyncModule()).newRuntime();
 		runtime.setMemoryLimit(memoryLimitBytes);
 		runtime.setMaxStackSize(maxStackSizeBytes);
 		const context = runtime.newContext();
 		this.runtime = runtime;
 		this.context = context;
-		this.setupConsole();
-		if (backend) this._backend = adaptBackendProtocol(backend);
-		this.injectVfs();
-		if (tools && tools.length > 0) this.injectTools(tools);
+		this.consoleBuffer = new ConsoleBuffer(maxResultChars);
+		if (captureConsole) this.setupConsole();
+		if (tools !== void 0 && tools.length > 0) this.injectTools(tools);
+		if (skillsEnabled) this.installModuleLoader();
+	}
+	/**
+	* Load the skill into cache on first access and replay cached errors.
+	*/
+	async ensureSkillLoaded(name) {
+		const cached = this.skillsLoaded.get(name);
+		if (cached !== void 0) return cached;
+		const cachedError = this.skillsFailed.get(name);
+		if (cachedError !== void 0) throw cachedError;
+		const ctx = this.skillsContext;
+		if (ctx === void 0) throw new Error(`Skill '${name}' referenced but skills are not configured for this session`);
+		const metadata = ctx.metadata.find((m) => m.name === name);
+		if (metadata === void 0) throw new Error(`Skill '${name}' referenced but not available on this agent`);
+		try {
+			const loaded = await loadSkill(metadata, ctx.backend);
+			this.skillsLoaded.set(name, loaded);
+			return loaded;
+		} catch (err) {
+			this.skillsFailed.set(name, err);
+			throw err;
+		}
+	}
+	async 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));
+		}
+		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);
+		if (source === void 0) return makeErrorSource(`Skill '${parsed.name}': '${parsed.rel}' not found in bundle`);
+		return source;
+	}
+	/**
+	* Canonicalize an `import` specifier. Bare specifiers pass through;
+	* relative specifiers are resolved against the importing module's path.
+	* Traversal out of a skill's `@/skills/<name>/` namespace is rejected.
+	*/
+	normalizeSpecifier(base, requested) {
+		if (!(requested.startsWith("./") || requested.startsWith("../"))) return requested;
+		const parsed = parseSkillSpecifier(base);
+		const resolved = posixJoin(parsed !== void 0 && parsed.rel === void 0 ? base : posixDirname(base), requested);
+		const skillPrefix = matchSkillPrefix(base);
+		if (skillPrefix === void 0) return resolved;
+		if (!resolved.startsWith(`${skillPrefix}/`)) return `__resolve_error__:${requested} escapes ${skillPrefix}`;
+		return resolved;
+	}
+	/**
+	* Wire the QuickJS module loader and normalizer on this session's runtime.
+	*/
+	installModuleLoader() {
+		if (this.runtime === null) return;
+		this.runtime.setModuleLoader(async (specifier) => this.resolveSpecifier(specifier), (base, requested) => this.normalizeSpecifier(base, requested));
+	}
+	/**
+	* Initialise the per-eval PTC counter. Called at the top of every `eval()`.
+	*/
+	resetPtcBudget() {
+		this.ptcCallsRemaining = this.maxPtcCalls === null ? null : this.maxPtcCalls;
+	}
+	/**
+	* Decrement the PTC call counter and throw if the budget is exhausted.
+	* `null` budget means unlimited — returns immediately without decrementing.
+	*/
+	consumePtcBudget(functionName) {
+		if (this.ptcCallsRemaining === null) return;
+		if (this.ptcCallsRemaining > 0) {
+			this.ptcCallsRemaining--;
+			return;
+		}
+		const limit = this.maxPtcCalls ?? 0;
+		throw new PTCCallBudgetExceededError({
+			limit,
+			attempted: limit + 1,
+			functionName
+		});
 	}
 	/**
 	* Get or create a session for the given id.
@@ -322,10 +686,7 @@ var ReplSession = class ReplSession {
 	*/
 	static getOrCreate(id, options = {}) {
 		const existing = ReplSession.sessions.get(id);
-		if (existing) {
-			if (options.backend) existing._backend = adaptBackendProtocol(options.backend);
-			return existing;
-		}
+		if (existing) return existing;
 		const session = new ReplSession(id, options);
 		ReplSession.sessions.set(id, session);
 		return session;
@@ -337,6 +698,31 @@ var ReplSession = class ReplSession {
 		return ReplSession.sessions.get(id) ?? null;
 	}
 	/**
+	* Returns true if any session exists whose key equals `threadId` or starts
+	* with `threadId:`. Useful for tests that need to confirm a session was
+	* created without knowing the full `threadId:middlewareId` key.
+	*/
+	static hasAnyForThread(threadId) {
+		const prefix = `${threadId}:`;
+		for (const key of ReplSession.sessions.keys()) if (key === threadId || key.startsWith(prefix)) return true;
+		return false;
+	}
+	/**
+	* Dispose and remove the session with the given key, if it exists.
+	*/
+	static deleteSession(key) {
+		const session = ReplSession.sessions.get(key);
+		if (session) session.dispose();
+	}
+	/**
+	* Push the current skills metadata + backend into the session.
+	* Called by the middleware once per `eval` invocation, before eval runs.
+	* Pass `undefined` to clear the context (no skill imports will resolve).
+	*/
+	setSkillsContext(ctx) {
+		this.skillsContext = ctx;
+	}
+	/**
 	* Evaluate code in this session.
 	*
 	* Lazily starts the QuickJS runtime on the first call. Code is
@@ -349,88 +735,94 @@ var ReplSession = class ReplSession {
 		await this.ensureStarted();
 		const runtime = this.runtime;
 		const context = this.context;
-		this.logs.length = 0;
-		if (timeoutMs >= 0) runtime.setInterruptHandler(shouldInterruptAfterDeadline(Date.now() + timeoutMs));
-		else runtime.setInterruptHandler(() => false);
-		const transformed = transformForEval(code);
-		const result = await context.evalCodeAsync(transformed);
-		if (result.error) {
-			const error = context.dump(result.error);
-			result.error.dispose();
+		const drainLogs = () => {
+			const [raw, dropped] = this.consoleBuffer.drain();
 			return {
-				ok: false,
-				error,
-				logs: [...this.logs]
+				logs: raw.length > 0 ? raw.split("\n").filter((l) => l.length > 0) : [],
+				logsDroppedChars: dropped
 			};
-		}
-		const promiseState = context.getPromiseState(result.value);
-		if (promiseState.type === "fulfilled") {
-			if (promiseState.notAPromise) {
-				const value = context.dump(result.value);
-				result.value.dispose();
+		};
+		this.resetPtcBudget();
+		try {
+			if (timeoutMs >= 0) runtime.setInterruptHandler(shouldInterruptAfterDeadline(Date.now() + timeoutMs));
+			else runtime.setInterruptHandler(() => false);
+			const transformed = transformForEval(code);
+			const result = await context.evalCodeAsync(transformed);
+			if (result.error) {
+				const error = context.dump(result.error);
+				result.error.dispose();
 				return {
-					ok: true,
-					value,
-					logs: [...this.logs]
+					ok: false,
+					error,
+					...drainLogs()
 				};
 			}
-			const value = context.dump(promiseState.value);
-			promiseState.value.dispose();
-			result.value.dispose();
-			return {
-				ok: true,
-				value,
-				logs: [...this.logs]
-			};
-		}
-		if (promiseState.type === "rejected") {
-			const error = context.dump(promiseState.error);
-			promiseState.error.dispose();
-			result.value.dispose();
-			return {
-				ok: false,
-				error,
-				logs: [...this.logs]
-			};
-		}
-		const noTimeout = timeoutMs < 0;
-		const deadline = noTimeout ? Infinity : Date.now() + timeoutMs;
-		while (noTimeout || Date.now() < deadline) {
-			context.runtime.executePendingJobs();
-			const state = context.getPromiseState(result.value);
-			if (state.type === "fulfilled") {
-				const value = context.dump(state.value);
-				state.value.dispose();
+			const promiseState = context.getPromiseState(result.value);
+			if (promiseState.type === "fulfilled") {
+				if (promiseState.notAPromise) {
+					const value = context.dump(result.value);
+					result.value.dispose();
+					return {
+						ok: true,
+						value,
+						...drainLogs()
+					};
+				}
+				const value = context.dump(promiseState.value);
+				promiseState.value.dispose();
 				result.value.dispose();
 				return {
 					ok: true,
 					value,
-					logs: [...this.logs]
+					...drainLogs()
 				};
 			}
-			if (state.type === "rejected") {
-				const error = context.dump(state.error);
-				state.error.dispose();
+			if (promiseState.type === "rejected") {
+				const error = context.dump(promiseState.error);
+				promiseState.error.dispose();
 				result.value.dispose();
 				return {
 					ok: false,
 					error,
-					logs: [...this.logs]
+					...drainLogs()
 				};
 			}
-			await new Promise((r) => setTimeout(r, 1));
+			const noTimeout = timeoutMs < 0;
+			const deadline = noTimeout ? Infinity : Date.now() + timeoutMs;
+			while (noTimeout || Date.now() < deadline) {
+				context.runtime.executePendingJobs();
+				const state = context.getPromiseState(result.value);
+				if (state.type === "fulfilled") {
+					const value = context.dump(state.value);
+					state.value.dispose();
+					result.value.dispose();
+					return {
+						ok: true,
+						value,
+						...drainLogs()
+					};
+				}
+				if (state.type === "rejected") {
+					const error = context.dump(state.error);
+					state.error.dispose();
+					result.value.dispose();
+					return {
+						ok: false,
+						error,
+						...drainLogs()
+					};
+				}
+				await new Promise((r) => setTimeout(r, 1));
+			}
+			result.value.dispose();
+			return {
+				ok: false,
+				error: { message: "Promise timed out — execution interrupted" },
+				...drainLogs()
+			};
+		} finally {
+			this.ptcCallsRemaining = null;
 		}
-		result.value.dispose();
-		return {
-			ok: false,
-			error: { message: "Promise timed out — execution interrupted" },
-			logs: [...this.logs]
-		};
-	}
-	async flushWrites(backend) {
-		const adapted = adaptBackendProtocol(backend);
-		const writes = this.pendingWrites.splice(0);
-		for (const { path, content } of writes) await adapted.write(path, content);
 	}
 	dispose() {
 		try {
@@ -459,7 +851,6 @@ var ReplSession = class ReplSession {
 	}
 	setupConsole() {
 		const context = this.context;
-		const logs = this.logs;
 		const consoleHandle = context.newObject();
 		for (const method of [
 			"log",
@@ -470,7 +861,8 @@ var ReplSession = class ReplSession {
 		]) {
 			const fnHandle = context.newFunction(method, (...args) => {
 				const formatted = args.map((a) => context.dump(a)).map((a) => typeof a === "object" && a !== null ? JSON.stringify(a) : String(a)).join(" ");
-				logs.push(method === "log" || method === "info" || method === "debug" ? formatted : `[${method}] ${formatted}`);
+				const line = method === "log" || method === "info" || method === "debug" ? formatted : `[${method}] ${formatted}`;
+				this.consoleBuffer.append(line + "\n");
 			});
 			context.setProp(consoleHandle, method, fnHandle);
 			fnHandle.dispose();
@@ -478,67 +870,6 @@ var ReplSession = class ReplSession {
 		context.setProp(context.global, "console", consoleHandle);
 		consoleHandle.dispose();
 	}
-	injectVfs() {
-		const context = this.context;
-		const getBackend = () => this._backend;
-		const { pendingWrites } = this;
-		const readFileHandle = context.newFunction("readFile", (pathHandle) => {
-			const backend = getBackend();
-			if (!backend) {
-				const promise = context.newPromise();
-				const err = context.newError("Backend not available");
-				promise.reject(err);
-				err.dispose();
-				promise.settled.then(context.runtime.executePendingJobs);
-				return promise.handle;
-			}
-			const path = context.getString(pathHandle);
-			const promise = context.newPromise();
-			(async () => {
-				try {
-					const result = await backend.readRaw(path);
-					if (result.error || !result.data) {
-						const err = context.newError(`ENOENT: no such file or directory '${path}'.`);
-						promise.reject(err);
-						err.dispose();
-					} else {
-						const content = Array.isArray(result.data.content) ? result.data.content.join("\n") : typeof result.data.content === "string" ? result.data.content : null;
-						if (content === null) {
-							const err = context.newError(`Cannot read binary file '${path}' as text.`);
-							promise.reject(err);
-							err.dispose();
-							return;
-						}
-						const val = context.newString(content);
-						promise.resolve(val);
-						val.dispose();
-					}
-				} catch {
-					const err = context.newError(`ENOENT: no such file or directory '${path}'.`);
-					promise.reject(err);
-					err.dispose();
-				}
-				promise.settled.then(context.runtime.executePendingJobs);
-			})();
-			return promise.handle;
-		});
-		context.setProp(context.global, "readFile", readFileHandle);
-		readFileHandle.dispose();
-		const writeFileHandle = context.newFunction("writeFile", (pathHandle, contentHandle) => {
-			const path = context.getString(pathHandle);
-			const content = context.getString(contentHandle);
-			const promise = context.newPromise();
-			pendingWrites.push({
-				path,
-				content
-			});
-			promise.resolve(context.undefined);
-			promise.settled.then(context.runtime.executePendingJobs);
-			return promise.handle;
-		});
-		context.setProp(context.global, "writeFile", writeFileHandle);
-		writeFileHandle.dispose();
-	}
 	injectTools(tools) {
 		const context = this.context;
 		const toolsNs = context.newObject();
@@ -549,6 +880,7 @@ var ReplSession = class ReplSession {
 				const promise = context.newPromise();
 				(async () => {
 					try {
+						this.consumePtcBudget(camelName);
 						const rawInput = typeof input === "object" && input !== null ? input : {};
 						const result = await t.invoke(rawInput);
 						const val = context.newString(typeof result === "string" ? result : JSON.stringify(result));
@@ -574,74 +906,26 @@ var ReplSession = class ReplSession {
 //#endregion
 //#region src/middleware.ts
 /**
-* QuickJS REPL middleware for deepagents.
+* REPL 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)
-* - VFS integration via readFile/writeFile
-* - Programmatic tool calling (PTC)
-*/
-/**
-* Backend-provided tools excluded from PTC by default.
-* These are redundant inside the REPL since VFS helpers (readFile/writeFile)
-* already cover file I/O against the agent's in-memory working set.
-*/
-const DEFAULT_PTC_EXCLUDED_TOOLS = [
-	"ls",
-	"read_file",
-	"write_file",
-	"edit_file",
-	"glob",
-	"grep",
-	"execute"
-];
-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 filesystem** — only the helpers below. Do not attempt \`fetch\`, \`require\`, or \`import\`.
-  - **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.
-
-  ### First-time usage
-
-  \`\`\`typescript
-  // Read a file from the agent's virtual filesystem
-  const raw: string = await readFile("/data.json");
-  const data = JSON.parse(raw) as { n: number };
-  console.log(data);
-
-  // Write results back
-  await writeFile("/output.txt", JSON.stringify({ result: data.n }));
-  \`\`\`
-
-  ### API Reference — built-in globals
-
-  \`\`\`typescript
-  /**
-   * Read a file from the agent's virtual filesystem. Throws if the file does not exist.
-   */
-  async readFile(path: string): Promise<string>
-
-  /**
-   * Write a file to the agent's virtual filesystem.
-   */
-  async writeFile(path: string, content: string): Promise<void>
-  \`\`\`
-
-  ### Limitations
+* - Programmatic tool calling (PTC) — expose agent or custom tools inside the REPL
+*/
+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.
 */
@@ -678,74 +962,108 @@ async function generatePtcPrompt(tools) {
   `;
 }
 /**
-* Create the QuickJS REPL middleware.
+* Resolves a mixed list of tool names and tool instances into a flat list of
+* StructuredToolInterface objects. Strings are looked up by name in agentTools;
+* instances are included directly without requiring agent registration. Strings
+* that don't match any agent tool are silently omitted.
 */
-function createQuickJSMiddleware(options = {}) {
-	const { backend = (runtime) => new StateBackend(runtime), ptc = false, memoryLimitBytes = DEFAULT_MEMORY_LIMIT, maxStackSizeBytes = DEFAULT_MAX_STACK_SIZE, executionTimeoutMs = DEFAULT_EXECUTION_TIMEOUT, systemPrompt: customSystemPrompt = null } = options;
-	const usePtc = ptc !== false;
-	const baseSystemPrompt = customSystemPrompt || REPL_SYSTEM_PROMPT;
+function resolveToolList(items, agentTools) {
+	const agentByName = new Map(agentTools.map((t) => [t.name, t]));
+	return items.flatMap((item) => {
+		if (typeof item === "string") {
+			const found = agentByName.get(item);
+			return found ? [found] : [];
+		}
+		return [item];
+	});
+}
+/**
+* Pull `skillsMetadata` from the task input, resolve the backend, and push
+* both into the session. Short-circuits with a `SkillNotAvailable` error if
+* the source references skills the agent doesn't have.
+*/
+async function prepareSkillsForEval(session, skillsBackend, code) {
+	const taskInput = getCurrentTaskInput();
+	const metadata = taskInput?.skillsMetadata ?? [];
+	const referenced = scanSkillReferences(code);
+	if (referenced.size > 0) {
+		const known = new Set(metadata.map((m) => m.name));
+		const missing = [];
+		for (const name of referenced) if (!known.has(name)) missing.push(name);
+		if (missing.length > 0) {
+			session.setSkillsContext(void 0);
+			return formatSkillNotAvailable(missing);
+		}
+	}
+	const resolved = await resolveBackend(skillsBackend, { state: taskInput });
+	session.setSkillsContext({
+		metadata,
+		backend: resolved
+	});
+}
+/**
+* Create the REPL middleware.
+*/
+function createREPLMiddleware(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({
+		toolName,
+		timeout: executionTimeoutMs / 1e3,
+		memoryLimitMb: Math.floor(memoryLimitBytes / (1024 * 1024))
+	});
+	const middlewareId = crypto.randomUUID();
 	let cachedPtcPrompt = null;
 	let ptcTools = [];
 	function filterToolsForPtc(allTools) {
-		if (ptc === false) return [];
-		const candidates = allTools.filter((t) => t.name !== "js_eval");
-		if (ptc === true) {
-			const excluded = new Set(DEFAULT_PTC_EXCLUDED_TOOLS);
-			return candidates.filter((t) => !excluded.has(t.name));
-		}
-		if (Array.isArray(ptc)) {
-			const included = new Set(ptc);
-			return candidates.filter((t) => included.has(t.name));
-		}
-		if ("include" in ptc) {
-			const included = new Set(ptc.include);
-			return candidates.filter((t) => included.has(t.name));
-		}
-		if ("exclude" in ptc) {
-			const excluded = new Set([...DEFAULT_PTC_EXCLUDED_TOOLS, ...ptc.exclude]);
-			return candidates.filter((t) => !excluded.has(t.name));
-		}
-		return [];
+		if (!ptc) return [];
+		return resolveToolList(ptc, allTools.filter((t) => t.name !== toolName));
 	}
 	return createMiddleware({
-		name: "QuickJSMiddleware",
+		name: "REPLMiddleware",
 		tools: [tool(async (input, config) => {
-			const threadId = config.configurable?.thread_id || "__default__";
-			const resolvedBackend = await resolveBackend(backend, {
-				...config,
-				state: getCurrentTaskInput(config) || {}
-			});
-			const session = ReplSession.getOrCreate(threadId, {
+			const sessionKey = `${config.configurable?.thread_id || "__default__"}:${middlewareId}`;
+			const session = ReplSession.getOrCreate(sessionKey, {
 				memoryLimitBytes,
 				maxStackSizeBytes,
-				backend: resolvedBackend,
-				tools: ptcTools
+				maxPtcCalls,
+				tools: ptcTools,
+				skillsEnabled: skillsBackend !== void 0,
+				maxResultChars,
+				captureConsole
 			});
-			const result = await session.eval(input.code, executionTimeoutMs);
-			await session.flushWrites(resolvedBackend);
-			return formatReplResult(result);
+			if (skillsBackend !== void 0) {
+				const setupError = await prepareSkillsForEval(session, skillsBackend, input.code);
+				if (setupError !== void 0) return setupError;
+			}
+			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 readFile(path) and writeFile(path, content) for file access.
         Use console.log() for output. Returns the result of the last expression.
+        If file or other tools are available, call them via the tools namespace: await tools.readFile({ path }).
+        If skills are configured, dynamically import them: await import("@/skills/<name>").
       `,
+			metadata: { ls_code_input_language: "javascript" },
 			schema: z.object({ code: z.string().describe("TypeScript/JavaScript code to evaluate in the sandboxed REPL") })
 		})],
 		wrapModelCall: async (request, handler) => {
-			const agentTools = request.tools || [];
-			ptcTools = usePtc ? filterToolsForPtc(agentTools) : [];
+			ptcTools = filterToolsForPtc(request.tools || []);
 			if (ptcTools.length > 0 && !cachedPtcPrompt) cachedPtcPrompt = await generatePtcPrompt(ptcTools);
 			const systemMessage = request.systemMessage.concat(baseSystemPrompt).concat(cachedPtcPrompt || "");
 			return handler({
 				...request,
 				systemMessage
 			});
+		},
+		afterAgent: async (_state, runtime) => {
+			const sessionKey = `${runtime.configurable?.thread_id ?? "__default__"}:${middlewareId}`;
+			ReplSession.deleteSession(sessionKey);
 		}
 	});
 }
 //#endregion
-export { DEFAULT_EXECUTION_TIMEOUT, DEFAULT_MAX_STACK_SIZE, DEFAULT_MEMORY_LIMIT, DEFAULT_PTC_EXCLUDED_TOOLS, ReplSession, createQuickJSMiddleware, formatReplResult, 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, createREPLMiddleware, formatReplResult, formatSkillNotAvailable, loadSkill, scanSkillReferences, stripTypeSyntax, toCamelCase, transformForEval };
 
 //# sourceMappingURL=index.js.map