docs(deepagents): add interpreter library and swarm docs

src/docs.json

@@ -1579,6 +1579,12 @@
                         "oss/javascript/deepagents/streaming"
                       ]
                     },
+                    {
+                      "group": "Interpreter libraries",
+                      "pages": [
+                        "oss/javascript/deepagents/swarm"
+                      ]
+                    },
                     {
                       "group": "Frontend",
                       "pages": [

src/oss/deepagents/interpreters.mdx

@@ -62,7 +62,8 @@ QuickJS is the execution boundary for interpreter code. Explicit bridges, such a
 | One or two simple external calls | Normal tool calling |
 | A small program that loops, branches, retries, or aggregates results | Interpreter |
 | Many selected tool calls that should run from code | Interpreter with programmatic tool calling |
-| Reusable helpers used across threads | Interpreter with [interpreter skills](/oss/deepagents/skills#interpreter-skills) |
+| Pre-loaded importable modules for the interpreter | Interpreter with [interpreter libraries](#interpreter-libraries) |
+| Reusable helpers used across threads | Interpreter with [interpreter skills](/oss/deepagents/skills#execute-code-with-skills) |
 | Shell commands, package installs, tests, or full OS filesystem access | [Sandboxes](/oss/deepagents/sandboxes) |
 
 ## Add an interpreter to an agent
@@ -310,7 +311,190 @@ releaseSummary;
 
 Interpreter skills are [skills](/oss/deepagents/skills) that expose code modules to an interpreter. When configured with interpreter middleware, the agent can import these modules from code and use them for deterministic helper logic.
 
-Interpreter skills are useful when the agent needs reusable helpers for structured data workflows, such as sorting, grouping, scoring, parsing, validating, or aggregating data. For setup details, see [Interpreter skills](/oss/deepagents/skills#interpreter-skills).
+Interpreter skills are useful when the agent needs reusable helpers for structured data workflows, such as sorting, grouping, scoring, parsing, validating, or aggregating data. For setup details, see [Interpreter skills](/oss/deepagents/skills#execute-code-with-skills).
+
+:::js
+## Interpreter libraries
+
+Interpreter libraries are pre-loaded modules available inside the interpreter via standard `import` statements. Where interpreter skills are dynamically loaded at runtime based on the agent's judgment, libraries are loaded by the developer at configuration time. You decide what capabilities are available. The agent just imports and uses them.
+
+<Note>
+Interpreter libraries require `@langchain/quickjs>=0.3.0`.
+</Note>
+
+### The InterpreterLibrary interface
+
+Each library is an object with the following fields:
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `name` | `string` | Module name used in `import` statements (e.g., `"my-library"`) |
+| `description` | `string` | One-line summary shown to the agent in its system prompt |
+| `ptcTools` | `(string \| StructuredToolInterface)[]` | Host-side tools the library needs at runtime (e.g., `["write_file"]`) |
+| `source` | `string` | Entrypoint source code that runs inside the QuickJS sandbox |
+| `instructions` | `string` | Usage documentation injected into the agent's system prompt |
+| `files` | `Map<string, string>` | Optional additional source files the entrypoint can import |
+
+```typescript
+import type { InterpreterLibrary } from "@langchain/quickjs";
+
+const myLib: InterpreterLibrary = {
+  name: "my-library",
+  description: "Helpers for normalizing and scoring order records",
+  ptcTools: ["write_file"],
+  source: fs.readFileSync("./libraries/my-library/index.ts", "utf-8"),
+  instructions: fs.readFileSync("./libraries/my-library/INSTRUCTIONS.md", "utf-8"),
+};
+```
+
+**Source code** can be written in TypeScript — type annotations are stripped automatically before execution. The agent imports from the library with `import { ... } from "my-library"`.
+
+**Instructions** are injected into the agent's system prompt so the agent knows how to use the library. Write these as markdown with a quick start example and API reference.
+
+### PTC
+
+The `ptcTools` field declares which host-side [programmatic tool call](#programmatic-tool-calling) bridges the library needs. Inside library code, they're available on the `tools` global:
+
+```typescript
+declare const tools: {
+  writeFile?: (args: { file_path: string; content: string }) => Promise<string>;
+};
+
+export async function saveResults(data, path) {
+  await tools.writeFile({
+    file_path: path,
+    content: JSON.stringify(data, null, 2),
+  });
+}
+```
+
+PTC tools from all loaded libraries are merged into one shared set. If library A declares `["write_file"]` and library B declares `["read_file"]`, both tools are available to both libraries.
+
+### Load a library
+
+Pass library objects to `createCodeInterpreterMiddleware`:
+
+```typescript
+import * as fs from "node:fs";
+import { createDeepAgent } from "deepagents";
+import { createCodeInterpreterMiddleware } from "@langchain/quickjs";
+import type { InterpreterLibrary } from "@langchain/quickjs";
+
+const myLib: InterpreterLibrary = {
+  name: "my-library",
+  description: "Helpers for normalizing and scoring order records",
+  ptcTools: ["write_file"],
+  source: fs.readFileSync("./libraries/my-library/index.ts", "utf-8"),
+  instructions: fs.readFileSync("./libraries/my-library/INSTRUCTIONS.md", "utf-8"),
+};
+
+const agent = createDeepAgent({
+  model,
+  middleware: [
+    createCodeInterpreterMiddleware({
+      libraries: [myLib],
+    }),
+  ],
+});
+```
+
+The agent can then import from the library in interpreter code:
+
+```javascript
+import { normalize, score } from "my-library";
+
+const cleaned = normalize(orders);
+const ranked = score(cleaned, criteria);
+ranked.slice(0, 5);
+```
+
+### Interpreter libraries
+
+`@langchain/quickjs` ships with prebuilt libraries that you can add to any agent.
+
+| Library | Description |
+| --- | --- |
+| [Swarm](/oss/deepagents/swarm) | Parallel task fan-out with a table-based data model. Three-function API: `create`, `run`, `rows`. |
+
+### Custom libraries
+
+Libraries can import other libraries. This lets you build higher-level abstractions that hide dispatch complexity behind a single function call.
+
+For example, an `evaluator` library can import swarm internally:
+
+```typescript
+// evaluator/index.ts
+import { create, run, rows } from "swarm";
+
+export async function evaluate(candidates, criteria, options) {
+  const table = await create({
+    tasks: candidates.map((name, i) => ({ id: `c${i}`, name })),
+  });
+
+  await run(table.id, {
+    instruction: "Rate {name} on: " + criteria.map((c) => c.name).join(", "),
+    responseSchema: scoringSchema,
+  });
+
+  const topIds = rankByWeightedScore(await rows(table.id), criteria);
+
+  await run(table.id, {
+    instruction: "Research {name} in depth...",
+    subagentType: "researcher",
+    responseSchema: researchSchema,
+    filter: { column: "id", in: topIds },
+  });
+
+  await tools.writeFile({
+    file_path: "/evaluation/rankings.json",
+    content: JSON.stringify(await rows(table.id), null, 2),
+  });
+}
+```
+
+Load both libraries together:
+
+```typescript
+import * as fs from "node:fs";
+import { createCodeInterpreterMiddleware, swarm } from "@langchain/quickjs";
+import type { InterpreterLibrary } from "@langchain/quickjs";
+
+const swarmLib = swarm({ defaultModel, subagents: [...] });
+
+const evaluatorLib: InterpreterLibrary = {
+  name: "evaluator",
+  description: "Multi-pass evaluation pipeline built on swarm",
+  ptcTools: ["write_file"],
+  source: fs.readFileSync("./libraries/evaluator/index.ts", "utf-8"),
+  instructions: fs.readFileSync("./libraries/evaluator/INSTRUCTIONS.md", "utf-8"),
+};
+
+const agent = createDeepAgent({
+  model,
+  middleware: [
+    createCodeInterpreterMiddleware({
+      libraries: [swarmLib, evaluatorLib],
+    }),
+  ],
+});
+```
+
+The agent writes one call and the library handles everything:
+
+```javascript
+import { evaluate } from "evaluator";
+
+await evaluate(
+  ["Rust", "Go", "Python", "TypeScript"],
+  [
+    { name: "Performance", weight: 0.3 },
+    { name: "Developer experience", weight: 0.4 },
+    { name: "Ecosystem", weight: 0.3 },
+  ],
+  { topN: 3 },
+);
+```
+:::
 
 :::python
 ## Snapshots and time travel
@@ -432,4 +616,5 @@ Every tool you expose through PTC is an outside capability that interpreter code
 | `maxResultChars` | `4000` | Maximum characters retained from console output, result, and error strings. |
 | `toolName` | `"eval"` | Name of the interpreter tool exposed to the model. |
 | `captureConsole` | `true` | Whether `console.log`, `console.warn`, and `console.error` output is captured. |
+| `libraries` | omitted | Array of `InterpreterLibrary` objects to pre-load into the interpreter. |
 :::