@langchain/quickjs 0.5.0 → 0.6.0

package/README.md

@@ -100,7 +100,9 @@ PTC configuration is progressive:
 
 ### Recursive Language Model (RLM)
 
-When the `task` tool is exposed via PTC, the agent can spawn sub-agents in parallel from within the REPL:
+When the agent has subagents configured, a `task()` global is available inside
+the REPL (no PTC needed), so the agent can spawn sub-agents in parallel from
+within the REPL:
 
 ```typescript
 const agent = createDeepAgent({
@@ -112,7 +114,7 @@ const agent = createDeepAgent({
       systemPrompt: "...",
     },
   ],
-  middleware: [createQuickJSMiddleware({ ptc: ["task"] })],
+  middleware: [createQuickJSMiddleware()],
 });
 ```
 
@@ -122,16 +124,21 @@ The agent then writes code like:
 const topics = ["quantum computing", "fusion energy", "CRISPR"];
 const results = await Promise.all(
   topics.map((topic) =>
-    tools.task({
+    task({
       description: `Research ${topic} in depth`,
       subagentType: "general-purpose",
     }),
   ),
 );
+// Aggregate and return the report from the eval; the agent then writes it to a
+// file with its own write_file tool.
 const report = topics.map((t, i) => `## ${t}\n${results[i]}`).join("\n\n");
-await writeFile("/research.md", report);
+report;
 ```
 
+> `task` cannot be exposed via `ptc` — it is reserved for the `task()` global,
+> so passing `ptc: ["task"]` throws.
+
 ## API
 
 ### `createQuickJSMiddleware(options?)`

package/dist/index.cjs

@@ -30,6 +30,8 @@ let quickjs_emscripten = require("quickjs-emscripten");
 let quickjs_emscripten_core = require("quickjs-emscripten-core");
 let json_schema_to_typescript = require("json-schema-to-typescript");
 let _langchain_core_utils_json_schema = require("@langchain/core/utils/json_schema");
+let _langchain_langgraph = require("@langchain/langgraph");
+let _langchain_core_messages = require("@langchain/core/messages");
 let acorn = require("acorn");
 let _sveltejs_acorn_typescript = require("@sveltejs/acorn-typescript");
 let estree_walker = require("estree-walker");
@@ -121,6 +123,59 @@ async function toolToTypeSignature(name, description, jsonSchema) {
   `;
 }
 //#endregion
+//#region src/coerce.ts
+/**
+* Coercion of tool / subagent return values for the QuickJS bridge.
+*
+* The deepagents `task` tool resolves to a LangGraph `Command` whose payload
+* carries the subagent's final message(s) under `update.messages`; some tools
+* return a `ToolMessage` or a list of messages. The interpreter bridges need
+* the underlying output, not the envelope, so this unwraps those shapes to the
+* content the model actually cares about.
+*/
+/**
+* Return the trailing message content from a `Command`'s `update.messages`,
+* scanning from the end for the last message that actually has content. Returns
+* the command unchanged when it has no message-shaped payload.
+*/
+function extractCommandContent(command) {
+	const update = command.update;
+	const messages = update !== null && typeof update === "object" ? update.messages : void 0;
+	if (Array.isArray(messages)) for (let i = messages.length - 1; i >= 0; i--) {
+		const message = messages[i];
+		if (_langchain_core_messages.BaseMessage.isInstance(message) && message.content != null) return message.content;
+	}
+	return command;
+}
+/**
+* Unwrap a LangChain `Command` / `ToolMessage` / message-list envelope to the
+* underlying content. Non-envelope values (strings, content-block arrays, plain
+* objects) are returned unchanged.
+*
+* @param value The raw value returned by a tool or subagent dispatch.
+* @returns The unwrapped content, or `value` itself when it isn't an envelope.
+*/
+function unwrapToolEnvelope(value) {
+	if (typeof value === "string") return value;
+	if ((0, _langchain_langgraph.isCommand)(value)) {
+		const inner = extractCommandContent(value);
+		return inner === value ? value : unwrapToolEnvelope(inner);
+	}
+	if (_langchain_core_messages.BaseMessage.isInstance(value)) return unwrapToolEnvelope(value.content);
+	if (Array.isArray(value)) {
+		for (let i = value.length - 1; i >= 0; i--) {
+			const entry = value[i];
+			if (_langchain_core_messages.BaseMessage.isInstance(entry)) return unwrapToolEnvelope(entry.content);
+			if ((0, _langchain_langgraph.isCommand)(entry)) {
+				const inner = extractCommandContent(entry);
+				if (inner !== entry) return unwrapToolEnvelope(inner);
+			}
+		}
+		return value;
+	}
+	return value;
+}
+//#endregion
 //#region src/transform.ts
 /**
 * AST-based code transform pipeline for the REPL.
@@ -422,6 +477,7 @@ function getSharedModule() {
 * @returns Plain string representation of the tool output.
 */
 function extractToolText(result) {
+	result = unwrapToolEnvelope(result);
 	if (typeof result === "string") return result;
 	if (Array.isArray(result)) {
 		const texts = [];
@@ -516,7 +572,7 @@ var ReplSession = class ReplSession {
 	subagentQueue = null;
 	bridgeDispatchRef = null;
 	/** Allowed keys in the subagent input object. */
-	static SUBAGENT_ALLOWED_KEYS = new Set([
+	static SUBAGENT_ALLOWED_KEYS = /* @__PURE__ */ new Set([
 		"description",
 		"subagentType",
 		"responseSchema"
@@ -926,8 +982,10 @@ function renderSubagentPrompt(toolName) {
     ### Dispatching Subagents with \`task\`
 
     \`task\` is your primitive for running configured subagents from inside the
-    JavaScript REPL. You orchestrate everything else - fan-out, filtering,
-    deduplication, multi-stage flow, and synthesis - in plain JavaScript.
+    JavaScript REPL. Your job here is to DISTRIBUTE work, not to do it yourself:
+    write JavaScript that fans work out to subagents and assembles their results.
+    You handle the orchestration - fan-out, filtering, deduplication, multi-stage
+    flow, and synthesis - in plain JavaScript.
 
     #### The primitive
 
@@ -945,13 +1003,19 @@ function renderSubagentPrompt(toolName) {
     the configured subagent names.
 
     \`description\` is the only prompt the subagent receives for this dispatch. Make
-    it complete: include the goal, constraints, relevant context, what to inspect,
-    and the exact shape or level of detail you expect back. Each dispatch is
-    stateless from the caller's perspective; you cannot send follow-up messages to
-    the same subagent run.
+    it complete: the goal, the constraints, what to inspect, and the exact shape
+    or level of detail you expect back. Give context as locators — file paths and
+    symbol names — not as pasted file contents. If you already read a file while
+    exploring, still pass its path and let the subagent read it; do not paste back
+    what you read. Each dispatch is stateless from the caller's perspective; you
+    cannot send follow-up messages to the same subagent run.
 
-    \`responseSchema\` is optional. When provided, the resolved value is already a
-    typed JavaScript value matching the schema. Do not call \`JSON.parse\` unless the
+    \`responseSchema\` is optional, but set it on any dispatch whose result feeds
+    later code. A deterministic, typed shape is what lets you compose the next
+    stage reliably — index it, sort it, compare fields, branch on it, merge it —
+    instead of parsing free-form text. This is what makes a whole workflow
+    composable as one script. When provided, the resolved value is already a typed
+    JavaScript value matching the schema; do not call \`JSON.parse\` unless the
     subagent intentionally returned a JSON string. Dynamic schemas work for
     declarative subagents; runnable-backed subagents reject dynamic schemas because
     their runnable is already compiled.
@@ -972,9 +1036,12 @@ function renderSubagentPrompt(toolName) {
     dispatch result back onto its item. Multi-stage analysis means: run a pass,
     filter or regroup the array in JS, then run another pass over the survivors.
 
-    Prefer one \`${toolName}\` call that performs the whole workflow. Splitting the
-    workflow across multiple \`${toolName}\` calls costs model turns and forces you to
-    re-establish state.
+    You can run the whole workflow in one \`${toolName}\` call or split it across
+    several — both are fine. A single end-to-end script (generate, compare, pick a
+    winner; or review every item, then synthesize) is clean when you can write it
+    in one go; splitting is also fine when you want to inspect results between
+    stages. Either way, don't redo work across calls — reuse what is already in
+    scope (see "Reuse what earlier evals left in scope" below).
 
     #### Fan out with bounded concurrency
 
@@ -983,13 +1050,15 @@ function renderSubagentPrompt(toolName) {
     enforces a hard per-REPL cap of 32 concurrent subagent calls.
 
     \`\`\`javascript
+    const files = ["/src/a.ts", "/src/b.ts", "/src/c.ts"]; // found while exploring
     const batchSize = 10;
     const reviewed = [];
-    for (let i = 0; i < items.length; i += batchSize) {
-      const batch = items.slice(i, i + batchSize);
-      reviewed.push(...(await Promise.all(batch.map(async (it) => {
+    for (let i = 0; i < files.length; i += batchSize) {
+      const batch = files.slice(i, i + batchSize);
+      reviewed.push(...(await Promise.all(batch.map(async (file) => {
         const result = await task({
-          description: "Review " + it.file + " for SQL injection. Cite line numbers.",
+          description: "Read " + file + " and review it for SQL injection. " +
+            "Cite line numbers.",
           subagentType: "reviewer",
           responseSchema: {
             type: "object",
@@ -1010,61 +1079,44 @@ function renderSubagentPrompt(toolName) {
             required: ["vulnerabilities"],
           },
         });
-        return { ...it, ...result };
+        return { file, ...result };
       }))));
     }
     \`\`\`
 
-    #### Use parent JS for cheap work; use subagents for agentic work
+    #### Explore with your own tools first, then distribute
 
-    Use JavaScript in the parent REPL for deterministic orchestration: joining
-    arrays, deduping, sorting, filtering, grouping, batching, and merging results.
-    If the \`tools.*\` namespace is exposed, also use it to pre-read files or collect
-    shared data once, then pass only the relevant content to each subagent in
-    \`description\`.
+    You already have your normal tools for reading, listing, globbing, and
+    grepping files. Use them to explore and understand the task BEFORE you write
+    the orchestration script. These are ordinary tool calls, separate from the
+    \`${toolName}\` tool: read the data file, list or glob the directory, grep for
+    what matters, then decide how to split the work.
 
-    Use \`task\` for work that benefits from an autonomous agentic loop: reading
-    or searching with the subagent's own tools, inspecting multiple files, following
-    leads, making judgment calls, or producing a final synthesized report.
+    Never write \`${toolName}\` code that spawns a subagent just to read or parse a
+    file or list a directory. That is a deterministic step you do yourself with a
+    direct tool call; spending a whole agent loop on it is wasteful.
 
-    #### Pre-read shared context in the parent when useful
+    Once you understand the shape of the work, you have creative freedom in how
+    you split it:
 
-    If many subagents need the same source list or file content and \`tools.*\` is
-    available, gather that context once in the parent REPL before dispatching:
+    - One dispatch per file or per record, when the items are already separate.
+    - Chunk a large input yourself — read it, split it, optionally write a small
+      input file per chunk — and dispatch one subagent per chunk.
+    - A cheap classification pass first, then deeper dispatches only for the items
+      that warrant them.
 
-    \`\`\`javascript
-    const files = (await tools.glob({ pattern: "src/**/*.ts" }))
-      .split("\\n")
-      .filter(Boolean);
+    Then write JavaScript in the \`${toolName}\` tool that distributes the heavy,
+    agentic work to subagents with \`task()\`: analyzing file contents, exploring a
+    codebase, making judgment calls, rewriting code, or synthesizing a report.
 
-    const items = await Promise.all(files.map(async (file) => {
-      const content = await tools.readFile({ file_path: file });
-      return { file, content };
-    }));
-
-    const batchSize = 10;
-    const results = [];
-    for (let i = 0; i < items.length; i += batchSize) {
-      const batch = items.slice(i, i + batchSize);
-      results.push(...(await Promise.all(batch.map(async (it) => {
-        const finding = await task({
-          description:
-            "Review this file for auth bypasses. Return concrete findings only.\\n\\n" +
-            "File: " + it.file + "\\n\\n" +
-            it.content,
-          subagentType: "reviewer",
-          responseSchema: {
-            type: "object",
-            properties: {
-              findings: { type: "array", items: { type: "object" } },
-            },
-            required: ["findings"],
-          },
-        });
-        return { ...it, ...finding };
-      }))));
-    }
-    \`\`\`
+    Hand each subagent a locator, not a payload. Subagents have their own file
+    tools, so for anything that lives in a file — a file to review, rewrite, or
+    audit — pass the path and let the subagent read it. Do NOT read a whole file
+    just to paste its contents into the description; that bloats every dispatch
+    and duplicates the file across them. Reserve inline content for small or
+    derived data that has no path of its own: a single parsed record, or a chunk
+    you split out of a larger input (write the chunk to its own file and pass that
+    path if it is large). Assemble the results in JS.
 
     #### Compose multiple stages
 
@@ -1073,67 +1125,89 @@ function renderSubagentPrompt(toolName) {
     only for those items.
 
     \`\`\`javascript
-    const tagged = [];
-    for (let i = 0; i < items.length; i += 10) {
-      const batch = items.slice(i, i + 10);
-      tagged.push(...(await Promise.all(batch.map(async (it) => {
-        const tag = await task({
-          description: "Classify " + it.file + " as handler, util, test, or config.",
-          subagentType: "reviewer",
-          responseSchema: {
-            type: "object",
-            properties: { kind: { type: "string" }, risky: { type: "boolean" } },
-            required: ["kind", "risky"],
-          },
-        });
-        return { ...it, ...tag };
-      }))));
-    }
+    const tagged = await Promise.all(files.map((file) =>
+      task({
+        description: "Read " + file + " and classify it as handler, util, " +
+          "test, or config.",
+        subagentType: "reviewer",
+        responseSchema: {
+          type: "object",
+          properties: { kind: { type: "string" }, risky: { type: "boolean" } },
+          required: ["kind", "risky"],
+        },
+      }).then((tag) => ({ file, ...tag }))
+    ));
 
     const riskyHandlers = tagged.filter((it) => it.kind === "handler" && it.risky);
-    const deepReviews = [];
-    for (let i = 0; i < riskyHandlers.length; i += 10) {
-      const batch = riskyHandlers.slice(i, i + 10);
-      deepReviews.push(...(await Promise.all(batch.map(async (it) => {
-        const review = await task({
-          description: "Deep security review of " + it.file + ". Cite line numbers.",
-          subagentType: "reviewer",
-        });
-        return { ...it, review };
-      }))));
-    }
+    const deepReviews = await Promise.all(riskyHandlers.map((it) =>
+      task({
+        description: "Deep security review of " + it.file + ". Cite line numbers.",
+        subagentType: "reviewer",
+      }).then((review) => ({ ...it, review }))
+    ));
     \`\`\`
 
-    #### Get results out without flooding your context
+    #### Return results via the last expression, not \`console.log\`
+
+    The value of the last expression in an \`${toolName}\` call (or a resolved
+    top-level \`await\`) is returned to you as the result. Make that final
+    expression the variable holding your result and read it from there.
+    \`console.log\` is only for incidental debugging: its output is capped and
+    truncated, while the returned value is not, so never \`console.log\` your
+    actual results.
+
+    Keep large intermediate sets in JS variables and return only a compact
+    summary or a small slice, not the entire dataset. To persist full output,
+    have a subagent write it, or write it with your own file tool outside the
+    \`${toolName}\` call.
+
+    #### Reuse what earlier evals left in scope
 
-    Keep large result sets in JS variables. Do not \`console.log\` the full result set.
-    If \`tools.writeFile\` is exposed, persist structured output from inside the eval:
+    The REPL is persistent within a turn: every top-level variable, function, and
+    class you declare is kept and is available in your next \`${toolName}\` call
+    (each is hoisted to global scope). So if a later step needs something an
+    earlier eval produced or bound, **reference that variable by name** — do not
+    write a new literal that re-types data a previous eval already returned or
+    computed.
+
+    If you catch yourself pasting a big array or object of values you produced in
+    an earlier call, that is the tell: the variable is still in scope, so use it.
+    Re-typing prior results as a fresh literal wastes tokens and drifts from what
+    actually ran.
 
     \`\`\`javascript
-    await tools.writeFile({
-      file_path: "/results/subagent-output.json",
-      content: JSON.stringify(deepReviews),
-    });
-    \`\`\`
+    // An earlier eval bound this:
+    //   const auditResults = await Promise.all(files.map(/* ...audit... */));
 
-    Otherwise return a compact summary or a small slice of the results, not the
-    entire intermediate dataset.
+    // A later eval — reference it; do NOT paste the findings back in as a literal:
+    const findings = auditResults.flatMap((r) =>
+      r.findings.map((f) => ({ ...f, file: r.file }))
+    );
+    const verified = await Promise.all(findings.map((f) =>
+      task({ description: "Verify this finding: " + f.evidence, subagentType: "verifier" })
+        .then((v) => ({ ...f, ...v }))
+    ));
+    \`\`\`
 
-    #### Across evals
+    #### When the user asks for a "workflow"
 
-    Variables persist according to the interpreter persistence mode above, but
-    re-establish what you need in each eval. Doing the whole workflow in one
-    \`${toolName}\` call is usually simplest.
+    If the user's request mentions running a "workflow" (or otherwise uses the
+    word "workflow"), fan the work out to subagents rather than doing it all
+    yourself. Explore with your own tools first as needed, then write JavaScript
+    in the \`${toolName}\` tool that dispatches subagents with \`task()\` and
+    assembles their results. The point is to distribute the heavy work in
+    parallel, not to grind through it one tool call at a time.
   `;
 }
 function renderReplSystemPrompt(opts) {
+	const sideEffects = opts.hasPtc ? " External side effects from inside the REPL are reachable only via the `tools.*` namespace documented below." : " The REPL is pure computation; do any filesystem or other I/O with your normal tools, outside this tool.";
 	return dedent.default`
     ### Interpreter
 
     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.
-    - Runtime sandbox: no built-in filesystem, network, stdlib, or wall-clock APIs (\`fetch\`, \`require\`, \`fs\`, \`process\`, real \`Date.now()\` are unavailable or stubbed). External side effects from inside the REPL are only reachable via the \`tools.*\` namespace when it is exposed (see below); without it, the REPL is pure computation.
+    - Runtime sandbox: no built-in filesystem, network, stdlib, or wall-clock APIs (\`fetch\`, \`require\`, \`fs\`, \`process\`, real \`Date.now()\` are unavailable or stubbed).${sideEffects}
     - Timeout: ${opts.timeout}s per call. Memory: ${opts.memoryLimitMb} MB total.
     - \`console.log\` output is captured and returned alongside the result.
   `;
@@ -1178,10 +1252,14 @@ async function generatePtcPrompt(tools) {
 * 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.
+*
+* Throws if the subagent `task` tool is requested (by name or instance): it is
+* reserved for the `task()` global and cannot be a `tools.*` PTC member.
 */
 function resolveToolList(items, agentTools) {
 	const agentByName = new Map(agentTools.map((t) => [t.name, t]));
 	return items.flatMap((item) => {
+		if ((typeof item === "string" ? item : item.name) === "task") throw new Error("The subagent `task` tool cannot be exposed via `ptc`. It is always available as the top-level `task()` global inside the REPL (with `subagentType` and `responseSchema` support); exposing it through the `tools.*` namespace would create a second, conflicting dispatch path that drops `responseSchema`. Remove \"task\" from `ptc`.");
 		if (typeof item === "string") {
 			const found = agentByName.get(item);
 			return found ? [found] : [];
@@ -1196,11 +1274,6 @@ function createCodeInterpreterMiddleware(options = {}) {
 	const { ptc, memoryLimitBytes = DEFAULT_MEMORY_LIMIT, maxStackSizeBytes = DEFAULT_MAX_STACK_SIZE, executionTimeoutMs = DEFAULT_EXECUTION_TIMEOUT, systemPrompt: customSystemPrompt = null, maxPtcCalls = 256, maxResultChars = DEFAULT_MAX_RESULTS_CHARS, toolName = DEFAULT_TOOL_NAME, captureConsole = true, subagents = true } = options;
 	const maxSubagentConcurrency = subagents ? 32 : 0;
 	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 = [];
@@ -1223,16 +1296,16 @@ function createCodeInterpreterMiddleware(options = {}) {
 					...hasSchema && { [deepagents.SUBAGENT_RESPONSE_FORMAT_CONFIG_KEY]: input.responseSchema }
 				}
 			};
-			const result = await subagentTaskTool.invoke({
+			const content = unwrapToolEnvelope(await subagentTaskTool.invoke({
 				description: input.description,
 				subagent_type: input.subagentType
-			}, toolConfig);
-			if (hasSchema && typeof result === "string") try {
-				return JSON.parse(result);
+			}, toolConfig));
+			if (hasSchema && typeof content === "string") try {
+				return JSON.parse(content);
 			} catch {
-				return result;
+				return content;
 			}
-			return result;
+			return content;
 		};
 	}
 	return (0, langchain.createMiddleware)({
@@ -1270,6 +1343,12 @@ function createCodeInterpreterMiddleware(options = {}) {
 			ptcTools = filterToolsForPtc(agentTools);
 			if (!taskTool && maxSubagentConcurrency > 0) taskTool = findTaskTool(agentTools);
 			if (ptcTools.length > 0 && !cachedPtcPrompt) cachedPtcPrompt = await generatePtcPrompt(ptcTools);
+			const baseSystemPrompt = customSystemPrompt || renderReplSystemPrompt({
+				toolName,
+				timeout: executionTimeoutMs / 1e3,
+				memoryLimitMb: Math.floor(memoryLimitBytes / (1024 * 1024)),
+				hasPtc: ptcTools.length > 0
+			});
 			const subagentPrompt = taskTool && maxSubagentConcurrency > 0 ? renderSubagentPrompt(toolName) : "";
 			const systemMessage = request.systemMessage.concat(baseSystemPrompt).concat(subagentPrompt).concat(cachedPtcPrompt || "");
 			return handler({