@zerowidth/workbench-sdk 2.7.1 → 2.8.0

package/README.md

@@ -540,6 +540,52 @@ Optional store members: `held: true` with `write`/`delete` returning
 sub-agent never sees its caller's memory: pass
 `memory.forImport(importId) => ({ instance | path })` to give it its own.
 
+### Running Code
+
+Attach the **Run Code** tool to a model and it can write and run Python or
+JavaScript: load a CSV, compute something exactly, draw a chart. The engine
+never runs the code itself. You tell it where:
+
+```javascript
+// A sandbox service that speaks the HTTP contract below
+await Workbench.create(flow, {
+  codeExecutor: { url: "https://sandbox.example.com", apiKey: process.env.SANDBOX_KEY },
+});
+
+// Or your own executor over any sandbox you like
+import { CodeExecutorInterface } from "@zerowidth/workbench-sdk";
+class MySandbox extends CodeExecutorInterface {
+  async capabilities() { return { languages: ["python"], sessions: true, files: true }; }
+  async openSession() { /* → session id */ }
+  async run({ language, code, timeoutMs, session }, { signal }) {
+    /* → { stdout, stderr, result?, files?: [{ path, mimeType, data (base64) }], error? } */
+  }
+  async closeSession(id) { /* … */ }
+}
+await Workbench.create(flow, { codeExecutor: { instance: new MySandbox() } });
+```
+
+The HTTP contract is three JSON calls: `POST /sessions` → `{ id }`,
+`POST /run` with `{ language, code, timeoutMs, session? }` → the result above,
+and `DELETE /sessions/:id`. Answer `410` when a session is gone.
+
+Each `run()` gets one session, opened on the first call and closed when the
+run ends, so variables and files carry over between the model's calls within
+a run and never into the next run of a reused engine. An imported flow or a
+macro gets a session of its own, the way it gets its own memory; Run Code
+passed into an import as a tool still runs in the caller's session.
+
+A failure in the code comes back to the model as output (the traceback is in
+`stderr`) so it can fix it; a time limit, lost session or unreachable sandbox
+comes back as a tool error. The time limit is at most 120 seconds per call.
+Images the code produces (`image/png`, `jpeg`, `gif`, `webp`) reach the model
+as pictures, up to four per call and 5 MB each; every file is listed by path,
+type and size. Printed output and the `result` value are capped at 20,000
+characters each. `signal` is aborted when the run is cancelled or times out.
+
+Run the sandbox with no network access and pass it no secrets: the code is
+written by a model.
+
 ### Custom Node Types
 
 Create custom nodes by implementing:

package/nodes/run-code/run-code.config.json

@@ -0,0 +1,70 @@
+{
+  "display_name": "Run Code",
+  "tagline": "Run code in a sandbox",
+  "description": "Run Python or JavaScript in a sandbox with no internet access. Variables and files you create stay available to later calls in this run. Print what you want to see: printed output and errors come back to you. A matplotlib figure that is still open when the code finishes comes back as an image. Prefer small steps you can check over one long script.",
+  "icon": "code",
+  "category": "data",
+  "is_constant": false,
+  "is_plugin": true,
+  "is_output": false,
+  "inputs": [
+    {
+      "name": "code",
+      "display_name": "Code",
+      "type": "string",
+      "description": "The code to run.",
+      "required": true
+    },
+    {
+      "name": "language",
+      "display_name": "Language",
+      "type": "string",
+      "description": "python or javascript.",
+      "default": "python",
+      "options": ["python", "javascript"]
+    }
+  ],
+  "outputs": [
+    {
+      "name": "stdout",
+      "display_name": "Output",
+      "type": "string",
+      "description": "What the code printed."
+    },
+    {
+      "name": "stderr",
+      "display_name": "Errors",
+      "type": "string",
+      "description": "Warnings and errors, including a traceback when the code failed."
+    },
+    {
+      "name": "result",
+      "display_name": "Result",
+      "type": "any",
+      "description": "The value of the last expression, when the sandbox reports one."
+    },
+    {
+      "name": "files",
+      "display_name": "Files",
+      "type": "array",
+      "description": "Files the code created or changed: path, type and size, and a link when the host saved them."
+    },
+    {
+      "name": "content",
+      "display_name": "Content",
+      "type": "array",
+      "description": "Images the code produced, delivered to the model as pictures."
+    }
+  ],
+  "settings": [
+    {
+      "name": "timeout_seconds",
+      "display_name": "Time Limit (seconds)",
+      "type": "number",
+      "description": "How long one call may run before it is stopped, up to 120.",
+      "default": 60
+    }
+  ],
+  "timeout": 150000,
+  "retry_limit": 0
+}

package/nodes/run-code/run-code.process.js

@@ -0,0 +1,64 @@
+/**
+ * Run Code: the model writes code, a sandbox runs it. The sandbox comes
+ * from the host as config.integrations.codeExecutor, scoped to this run:
+ * the first call opens a session and every later call reuses it.
+ *
+ * A failure in the code itself is a result, not an error: the traceback
+ * is in stderr and the model's next move is to fix it. Only the sandbox
+ * failing (time limit, lost session, unreachable) throws.
+ */
+
+const IMAGE = /^image\/(png|jpeg|gif|webp)$/;
+// Inside the node's own 150s timeout, so the sandbox's limit is the one
+// that fires and the model is told which limit it hit.
+const MAX_SECONDS = 120;
+// What the model is shown per call. Larger or later images are still
+// listed in `files`.
+const MAX_IMAGES = 4;
+const MAX_IMAGE_BYTES = 5 * 1024 * 1024;
+
+export default async ({ inputs, settings, config }) => {
+  const executor = config.integrations?.codeExecutor;
+  if (!executor) {
+    throw new Error("No sandbox is available to run code. Pass config.codeExecutor to the engine.");
+  }
+  const code = typeof inputs.code === "string" ? inputs.code : "";
+  if (!code.trim()) throw new Error("There's no code to run.");
+  const language = inputs.language || "python";
+  const seconds = Math.min(MAX_SECONDS, Math.max(1, Number(settings?.timeout_seconds) || 60));
+  const timeoutMs = seconds * 1000;
+
+  const out = await executor.run({ language, code, timeoutMs, signal: config.signal });
+
+  if (out.error && out.error.kind !== "runtime") {
+    const reason =
+      out.error.kind === "timeout"
+        ? `The code ran past the ${timeoutMs / 1000}s limit and was stopped.`
+        : out.error.kind === "memory"
+          ? "The code ran out of memory and was stopped."
+          : out.error.message;
+    const printed = out.stdout ? `\n\nPrinted before it stopped:\n${out.stdout}` : "";
+    throw new Error(`${reason}${printed}`);
+  }
+
+  const produced = Array.isArray(out.files) ? out.files : [];
+  const images = produced.filter((f) => typeof f.data === "string" && IMAGE.test(f.mimeType ?? ""));
+  const shown = images.filter((f) => f.data.length * 0.75 <= MAX_IMAGE_BYTES).slice(0, MAX_IMAGES);
+  const content = shown.map((f) => ({ type: "image", data: f.data, mimeType: f.mimeType }));
+  const notShown = images.length - shown.length;
+  // Bytes never ride in `files`: the listing is what the model and the
+  // trace see, and images reach the model through `content` instead.
+  const files = produced.map(({ data: _data, ...meta }) => meta);
+
+  return {
+    stdout: out.stdout ?? "",
+    stderr:
+      (out.stderr ?? "") +
+      (notShown
+        ? `${out.stderr ? "\n" : ""}${notShown} image${notShown > 1 ? "s" : ""} not shown: at most ${MAX_IMAGES} per call, each up to 5 MB. They are still listed in files.`
+        : ""),
+    result: out.result ?? null,
+    files,
+    content,
+  };
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerowidth/workbench-sdk",
-  "version": "2.7.1",
+  "version": "2.8.0",
   "dependencies": {
     "adm-zip": "^0.5.16",
     "ajv": "^8.17.1",
@@ -47,7 +47,8 @@
     "test-flow": "node tests/test.flows.js",
     "test-kb": "node tests/test.kb-search.js && node tests/test.kb-graph.js",
     "test-custom-inference": "node tests/test.custom-inference.js",
-    "test-memory": "node tests/test.agent-memory.js"
+    "test-memory": "node tests/test.agent-memory.js",
+    "test-run-code": "node tests/test.run-code.js"
   },
   "author": "Peter Binggeser @ ZeroWidth, LLC",
   "license": "Apache-2.0",

package/src/index.js

@@ -14,6 +14,7 @@ import { validateKeys, validateFlow, validateInputs } from "./utilities/validato
 import { loadCustomTypes, typeCheck, convertType } from "./utilities/typers.js";
 import { createSafeToolName, isRemoteMCPTool, isManualToolNode, mapTypeToJSONSchema, getDirname } from "./utilities/helpers.js";
 import { sanitizeAPICallEvent } from "./utilities/sanitizeAPICall.js";
+import { withOwnCodeSession } from "./integrations/code-executor.js";
 
 
 /**
@@ -1186,6 +1187,21 @@ export default class Workbench {
    * This should be called when the engine is no longer needed to free up memory
    * @returns {Promise<void>}
    */
+  /**
+   * Close this engine's code session, if it opened one. Each run() gets
+   * its own, so a reused engine never carries one run's variables and
+   * files into the next. The sandbox would expire it on its own; closing
+   * frees it now.
+   */
+  async _closeCodeSession() {
+    if (!this.config.integrations?.codeExecutor?.close) return;
+    try {
+      await this.config.integrations.codeExecutor.close();
+    } catch (err) {
+      this.logDebug(`Failed to close the code session: ${err.message}`);
+    }
+  }
+
   async cleanup() {
     this.logDebug('Starting cleanup process...');
     
@@ -1218,6 +1234,10 @@ export default class Workbench {
         }
       }
 
+      // run() already closes the code session; this covers an engine
+      // whose run never finished.
+      await this._closeCodeSession();
+
       // Clean up any imported engines that were created
       // These are stored in the cache when import nodes are processed
       const rawStore = this.cache.getRawStore();
@@ -1661,6 +1681,7 @@ export default class Workbench {
       // Restore the inherited signal so a reused engine doesn't treat this run's
       // (possibly aborted) signal as an ancestor on the next run().
       this.config.signal = this._inheritedSignal;
+      await this._closeCodeSession();
     }
   }
 
@@ -1732,8 +1753,9 @@ export default class Workbench {
     // Create internal zv1 instance
     const internalEngine = new Workbench(internalFlow, {
       ...this.config,
-      // Pass through integrations and other config
-      integrations: this.config.integrations,
+      // Pass through integrations and other config. Code runs in a
+      // session of the macro's own: its run ending closes that one, not ours.
+      integrations: withOwnCodeSession(this.config.integrations),
       keys: this.config.keys,
       debug: this.config.debug,
       // Pass tools from parent context
@@ -3269,3 +3291,13 @@ export {
   InMemoryMemoryStore,
   normalizeMemoryPath,
 } from './integrations/memory-store.js';
+
+// Code execution: pass `config.codeExecutor.url` for a sandbox that
+// speaks the HTTP contract, or implement CodeExecutorInterface over your
+// own and pass `config.codeExecutor.instance`. The Run Code tool node
+// uses it. See integrations/code-executor.js.
+export {
+  CodeExecutorInterface,
+  HttpCodeExecutor,
+  CodeSessionLostError,
+} from './integrations/code-executor.js';

package/src/integrations/code-executor.js

@@ -0,0 +1,246 @@
+/**
+ * Code execution: the contract an executor fulfils, a client for an
+ * executor reached over HTTP, and the per-run wrapper the engine hands to
+ * the Run Code tool.
+ *
+ * The engine never runs code itself and never learns which sandbox does.
+ * The host passes `config.codeExecutor`:
+ *
+ *   { instance: <CodeExecutorInterface> }   — its own executor object
+ *   { url, apiKey?, headers?, getHeaders? } — an executor that speaks the
+ *                                              HTTP contract below
+ *
+ * HTTP contract (all JSON):
+ *
+ *   POST   {url}/sessions        → { id }
+ *   POST   {url}/run             ← RunRequest  → RunResult
+ *   DELETE {url}/sessions/{id}   → 204
+ *
+ * A session holds variables and files between calls. Sessions are
+ * optional: an executor that answers `capabilities.sessions = false`
+ * runs every call fresh.
+ */
+
+const OUTPUT_CAP = 20000;
+
+/**
+ * Thrown when the executor no longer has the session's state (it was
+ * restarted, or the call landed somewhere else). Distinct from a failure
+ * in the code itself: the model's next step is to run its setup again.
+ */
+export class CodeSessionLostError extends Error {
+  constructor() {
+    super(
+      "The sandbox restarted, so variables and files from earlier calls are gone. Run the setup code again before continuing."
+    );
+    this.name = "CodeSessionLostError";
+  }
+}
+
+/**
+ * The contract. Implement this over any sandbox and pass it as
+ * `config.codeExecutor.instance`.
+ */
+export class CodeExecutorInterface {
+  /** @returns {Promise<{ languages: string[], sessions: boolean, files: boolean }>} */
+  async capabilities() {
+    throw new Error("capabilities() not implemented");
+  }
+
+  /**
+   * @param {{ language: string, code: string, input?: unknown,
+   *   files?: { path: string, data: string }[], timeoutMs: number,
+   *   session?: string }} _request  file `data` is base64
+   * @param {{ signal?: AbortSignal }} [_options] aborted when the run is
+   *   cancelled or the node times out; stop waiting on the sandbox then
+   * @returns {Promise<{ stdout: string, stderr: string, result?: unknown,
+   *   files?: { path: string, mimeType?: string, data?: string, url?: string, size?: number }[],
+   *   error?: { kind: "timeout" | "memory" | "runtime" | "unsupported" | "session_lost", message: string },
+   *   usage?: { wallMs: number, cpuMs?: number } }>}
+   */
+  async run(_request, _options) {
+    throw new Error("run() not implemented");
+  }
+
+  /** @returns {Promise<string>} a session id */
+  async openSession() {
+    throw new Error("openSession() not implemented");
+  }
+
+  /** @param {string} _id */
+  async closeSession(_id) {}
+}
+
+/** An executor reached over HTTP. */
+export class HttpCodeExecutor extends CodeExecutorInterface {
+  constructor({ url, apiKey, headers, getHeaders, fetch: fetchImpl, capabilities } = {}) {
+    super();
+    if (!url) throw new Error("A code executor needs a url.");
+    this.url = url.replace(/\/+$/, "");
+    this.apiKey = apiKey;
+    this.headers = headers ?? {};
+    this.getHeaders = getHeaders;
+    this.fetch = fetchImpl ?? globalThis.fetch;
+    this.declared = capabilities;
+  }
+
+  async capabilities() {
+    return this.declared ?? { languages: ["python", "javascript"], sessions: true, files: true };
+  }
+
+  async request(method, path, body, signal) {
+    const headers = {
+      "content-type": "application/json",
+      ...this.headers,
+      ...(this.getHeaders ? await this.getHeaders() : {}),
+      ...(this.apiKey ? { authorization: `Bearer ${this.apiKey}` } : {}),
+    };
+    const res = await this.fetch(`${this.url}${path}`, {
+      method,
+      headers,
+      body: body === undefined ? undefined : JSON.stringify(body),
+      signal,
+    });
+    if (res.status === 204) return null;
+    const text = await res.text();
+    let data = null;
+    try {
+      data = text ? JSON.parse(text) : null;
+    } catch {
+      // Fall through with the raw text for the error below.
+    }
+    if (!res.ok) {
+      if (res.status === 410 || data?.error?.kind === "session_lost") throw new CodeSessionLostError();
+      const message = data?.error?.message ?? data?.error ?? text.slice(0, 300);
+      throw new Error(`The code executor refused the request (${res.status}): ${message}`);
+    }
+    return data;
+  }
+
+  async run(request, { signal } = {}) {
+    return this.request("POST", "/run", request, signal);
+  }
+
+  async openSession() {
+    const data = await this.request("POST", "/sessions", {});
+    if (!data?.id) throw new Error("The code executor did not return a session id.");
+    return data.id;
+  }
+
+  async closeSession(id) {
+    await this.request("DELETE", `/sessions/${encodeURIComponent(id)}`);
+  }
+}
+
+const cap = (text) => {
+  const value = typeof text === "string" ? text : "";
+  return value.length > OUTPUT_CAP
+    ? `${value.slice(0, OUTPUT_CAP)}\n… (cut: ${value.length - OUTPUT_CAP} more characters)`
+    : value;
+};
+
+// `result` is whatever the sandbox reports for the last expression; a
+// big one (a DataFrame, a long list) is capped like printed output.
+const capResult = (value) => {
+  if (value === undefined || value === null) return null;
+  if (typeof value === "string") return cap(value);
+  let json;
+  try {
+    json = JSON.stringify(value);
+  } catch {
+    return cap(String(value));
+  }
+  return json && json.length > OUTPUT_CAP ? cap(json) : value;
+};
+
+/**
+ * One run's view of an executor: opens a session on first use when the
+ * executor supports them, reuses it for every later call in the run, and
+ * closes it when the run ends. Output is capped here so a print loop
+ * cannot flood the conversation, whatever the executor allows.
+ *
+ * Every engine owns one of these. A sub-engine (an import or a macro)
+ * gets its own through forSubEngine(), so its session never shares
+ * state with its caller's and closing it leaves the caller's open.
+ */
+export class RunScopedCodeExecutor {
+  constructor(executor) {
+    this.executor = executor;
+    this.sessionId = null;
+    this.opening = null;
+  }
+
+  async capabilities() {
+    return this.executor.capabilities();
+  }
+
+  /** A fresh scope over the same executor, for a sub-engine. */
+  forSubEngine() {
+    return new RunScopedCodeExecutor(this.executor);
+  }
+
+  async session() {
+    const caps = await this.executor.capabilities();
+    if (!caps.sessions) return undefined;
+    if (this.sessionId) return this.sessionId;
+    this.opening ??= this.executor.openSession().then((id) => {
+      this.sessionId = id;
+      return id;
+    });
+    try {
+      return await this.opening;
+    } finally {
+      this.opening = null;
+    }
+  }
+
+  async run({ language, code, input, files, timeoutMs, signal }) {
+    const caps = await this.executor.capabilities();
+    if (!caps.languages.includes(language)) {
+      throw new Error(
+        `This sandbox runs ${caps.languages.join(" and ")}, not ${language}.`
+      );
+    }
+    const session = await this.session();
+    let result;
+    try {
+      result = await this.executor.run({ language, code, input, files, timeoutMs, session }, { signal });
+    } catch (err) {
+      if (err instanceof CodeSessionLostError) this.sessionId = null;
+      throw err;
+    }
+    if (result?.error?.kind === "session_lost") {
+      this.sessionId = null;
+      throw new CodeSessionLostError();
+    }
+    return {
+      ...result,
+      stdout: cap(result?.stdout),
+      stderr: cap(result?.stderr),
+      result: capResult(result?.result),
+    };
+  }
+
+  async close() {
+    const id = this.sessionId;
+    this.sessionId = null;
+    if (id) await this.executor.closeSession(id);
+  }
+}
+
+/**
+ * The integrations a sub-engine runs with: the caller's, except that
+ * code runs in a session of its own. Returns the same object when there
+ * is no code executor.
+ */
+export function withOwnCodeSession(integrations) {
+  if (!integrations?.codeExecutor?.forSubEngine) return integrations;
+  return { ...integrations, codeExecutor: integrations.codeExecutor.forSubEngine() };
+}
+
+/** From the host's `config.codeExecutor` to the run-scoped executor. */
+export function createCodeExecutor(codeExecutorConfig = {}) {
+  if (codeExecutorConfig.instance) return new RunScopedCodeExecutor(codeExecutorConfig.instance);
+  if (codeExecutorConfig.url) return new RunScopedCodeExecutor(new HttpCodeExecutor(codeExecutorConfig));
+  throw new Error("config.codeExecutor needs either an instance or a url.");
+}

package/src/utilities/loaders.js

@@ -6,6 +6,7 @@ import { convertImportToNodeType } from "./typers.js";
 import { getDirname, isRemoteMCPTool } from "./helpers.js";
 import { isOAuthKey, OAuthRefreshManager } from "./oauth.js";
 import { createMemory, flowUsesMemory } from "../integrations/memory-store.js";
+import { createCodeExecutor } from "../integrations/code-executor.js";
 
 
 /**
@@ -244,6 +245,12 @@ export async function loadIntegrations(config, flow = null) {
       integrations.memory = createMemory(config.memory ?? {});
   }
 
+  // Code execution (integrations/code-executor.js): only ever the host's
+  // sandbox. There is no built-in fallback that runs code in-process.
+  if (config.codeExecutor) {
+      integrations.codeExecutor = createCodeExecutor(config.codeExecutor);
+  }
+
   // Initialize OAuth refresh manager if any OAuth keys are present
   let oauthRefreshManager = null;
   const hasOAuthKeys = Object.values(config.keys || {}).some(key => isOAuthKey(key));

package/src/utilities/typers.js

@@ -6,6 +6,7 @@ import Workbench from "../index.js";
 import { getDirname } from "./helpers.js";
 import { loadTypeConverter } from "./typeConverters.js";
 import { createMemory, flowUsesMemory } from "../integrations/memory-store.js";
+import { withOwnCodeSession } from "../integrations/code-executor.js";
 
 const ajv = new Ajv();
 
@@ -338,6 +339,12 @@ export function convertImportToNodeType(importDef) {
         importConfig.memory = own;
       }
 
+      // An imported flow runs code in a session of its own, like memory:
+      // it never sees its caller's variables, and its cleanup below closes
+      // its session, not the caller's. Run Code attached to the caller and
+      // passed in as a tool still runs in the caller's session.
+      importConfig.integrations = withOwnCodeSession(importConfig.integrations ?? config.integrations);
+
       // If this import accepts plugins, create tool runners for parent context execution
       // Note: We need to access the parent engine (this) to find connected plugins
       let tools = {};