@dotcms/ai 26.10.20-1 → 26.10.21-1

package/format-result.cjs.js

@@ -0,0 +1,833 @@
+'use strict';
+
+var errors = require('./errors.cjs.js');
+var node_worker_threads = require('node:worker_threads');
+var zod = require('zod');
+
+/**
+ * The sandbox worker harness — the code that runs INSIDE the worker.
+ *
+ * It is identical for both backends (Node `worker_threads` and Bun Web Workers); the only
+ * difference is the transport, so each backend prepends a tiny bootstrap that defines two
+ * functions the harness calls — `__post(msg)` and `__onMessage(handler)` — and (for Node)
+ * neutralizes `require`. Keeping the harness in ONE place means a protocol change (e.g. the
+ * error round-tripping below) is written once, not copy-pasted into two ~150-line strings.
+ *
+ * Hoisted to a module constant (it is fully static) so it is not re-allocated per execution.
+ */
+const HARNESS_BODY = `
+      // Block direct network access — all calls must go through adapters
+      const __networkError = () => { throw new Error('Network access is disabled in sandbox'); };
+      const __disableGlobalApi = (name) => {
+        try {
+          Object.defineProperty(globalThis, name, { value: __networkError, writable: false, configurable: false });
+        } catch { /* ignore if already frozen */ }
+      };
+      __disableGlobalApi('fetch');
+      __disableGlobalApi('XMLHttpRequest');
+      __disableGlobalApi('WebSocket');
+      __disableGlobalApi('EventSource');
+      if (globalThis.navigator && typeof globalThis.navigator === 'object') {
+        try {
+          Object.defineProperty(globalThis.navigator, 'sendBeacon', { value: __networkError, writable: false, configurable: false });
+        } catch { /* ignore */ }
+      }
+
+      // Clean process environment so sandboxed code cannot read host secrets.
+      if (typeof process !== 'undefined') { process.env = {}; }
+
+      const logs = [];
+      const pendingCalls = new Map();
+      let callId = 0;
+
+      const console = {
+        log: (...args) => logs.push(args.map(a => typeof a === 'object' ? JSON.stringify(a) : String(a)).join(' ')),
+        warn: (...args) => logs.push('[WARN] ' + args.map(a => typeof a === 'object' ? JSON.stringify(a) : String(a)).join(' ')),
+        error: (...args) => logs.push('[ERROR] ' + args.map(a => typeof a === 'object' ? JSON.stringify(a) : String(a)).join(' ')),
+        info: (...args) => logs.push('[INFO] ' + args.map(a => typeof a === 'object' ? JSON.stringify(a) : String(a)).join(' ')),
+      };
+      globalThis.console = console;
+
+      globalThis.pick = (arr, fields) => {
+        if (!Array.isArray(arr)) return arr;
+        return arr.map(item => {
+          const result = {};
+          for (const field of fields) {
+            const parts = field.split('.');
+            let value = item;
+            let key = parts[parts.length - 1];
+            for (const part of parts) value = value?.[part];
+            result[key] = value;
+          }
+          return result;
+        });
+      };
+
+      globalThis.table = (arr, maxRows = 10) => {
+        if (!Array.isArray(arr) || arr.length === 0) return '(empty)';
+        const items = arr.slice(0, maxRows);
+        const keys = Object.keys(items[0]);
+        const header = '| ' + keys.join(' | ') + ' |';
+        const sep = '|' + keys.map(() => '---').join('|') + '|';
+        const rows = items.map(item => '| ' + keys.map(k => String(item[k] ?? '')).join(' | ') + ' |');
+        let result = [header, sep, ...rows].join('\\n');
+        if (arr.length > maxRows) result += '\\n... +' + (arr.length - maxRows) + ' more rows';
+        return result;
+      };
+
+      globalThis.count = (arr, field) => {
+        if (!Array.isArray(arr)) return {};
+        return arr.reduce((acc, item) => {
+          const key = String(item[field] ?? 'unknown');
+          acc[key] = (acc[key] || 0) + 1;
+          return acc;
+        }, {});
+      };
+
+      globalThis.sum = (arr, field) => {
+        if (!Array.isArray(arr)) return 0;
+        return arr.reduce((acc, item) => acc + (Number(item[field]) || 0), 0);
+      };
+
+      globalThis.first = (arr, n = 5) => {
+        if (!Array.isArray(arr)) return arr;
+        return arr.slice(0, n);
+      };
+
+      // Resolve OpenAPI $refs against spec.components.schemas, expanding nested refs up to
+      // 'depth' levels. Beyond depth, { $ref } objects are left verbatim so the model can
+      // resolve the next hop in a follow-up query (progressive disclosure). Only available in
+      // the search sandbox, where the 'spec' global is injected.
+      //
+      // THREE bounds, not one. 'depth' alone was never sufficient: it is chosen by the model,
+      // and asking for a bigger number is exactly what a model does when depth 2 looks
+      // truncated. Expansion copies the whole target subtree per $ref hop with no memo, so
+      // cost grows multiplicatively with fan-out — and the committed spec is NOT acyclic
+      // (self-refs on FolderView/MultiPart/Permissionable, the BodyPart -> MultiPart ->
+      // BodyPart cycle, and fan-out around 10 on PageView). resolveRef('PageView', 12) would
+      // exhaust the worker's heap and get it killed, which the caller sees as an opaque
+      // sandbox death with the accumulated logs lost. The formatSandboxResult cap does not
+      // help: that applies to the result string, long after the graph is built in memory.
+      globalThis.resolveRef = (schemaOrName, depth = 2) => {
+        const MAX_DEPTH = 5;
+        const MAX_NODES = 50000;
+        const spec = globalThis.spec;
+        const schemas = spec && spec.components && spec.components.schemas;
+        if (!schemas) {
+          throw new Error('resolveRef() needs the spec global (spec.components.schemas). It is only available in the search sandbox.');
+        }
+        // Clamped rather than rejected, and the clamp is self-evident in the output: an
+        // unexpanded { $ref } is the same signal the model already follows for a deeper hop.
+        const requested = Number(depth);
+        const maxDepth = Math.max(0, Math.min(Number.isFinite(requested) ? requested : 2, MAX_DEPTH));
+        let budget = MAX_NODES;
+        const nameOf = (ref) => String(ref).split('/').pop();
+        const expand = (node, d, path) => {
+          if (--budget < 0) {
+            throw new Error('resolveRef() expanded more than ' + MAX_NODES + ' nodes and was stopped before exhausting worker memory. Resolve a smaller schema, or use a lower depth and follow the remaining $refs in a second call.');
+          }
+          if (Array.isArray(node)) return node.map((item) => expand(item, d, path));
+          if (!node || typeof node !== 'object') return node;
+          if (typeof node.$ref === 'string') {
+            if (d <= 0) return node;
+            const name = nameOf(node.$ref);
+            // Already on this branch's ancestry: expanding again would recurse forever on a
+            // self-referential or mutually-referential schema. Leaving the $ref verbatim is
+            // the same progressive-disclosure contract as running out of depth.
+            if (path.indexOf(name) !== -1) return node;
+            const target = schemas[name];
+            if (!target) return node;
+            return expand(target, d - 1, path.concat(name));
+          }
+          const out = {};
+          for (const key of Object.keys(node)) out[key] = expand(node[key], d, path);
+          return out;
+        };
+        if (typeof schemaOrName === 'string') {
+          const name = nameOf(schemaOrName);
+          const target = schemas[name];
+          if (!target) {
+            throw new Error('Unknown schema "' + schemaOrName + '". List names with Object.keys(spec.components.schemas).');
+          }
+          return expand(target, maxDepth, [name]);
+        }
+        return expand(schemaOrName, maxDepth, []);
+      };
+
+      __onMessage(async (msg) => {
+        const { type, data } = msg;
+
+        if (type === 'init') {
+          const { variables, adapterMethods, globals } = data;
+
+          for (const [key, value] of Object.entries(variables || {})) {
+            globalThis[key] = value;
+          }
+
+          for (const [key, value] of Object.entries(globals || {})) {
+            globalThis[key] = value;
+          }
+
+          globalThis.adapters = {};
+          for (const [adapterName, methods] of Object.entries(adapterMethods)) {
+            const adapterObj = {};
+            for (const methodName of methods) {
+              adapterObj[methodName] = async (...args) => {
+                const id = ++callId;
+                return new Promise((resolve, reject) => {
+                  pendingCalls.set(id, { resolve, reject });
+                  __post({
+                    type: 'adapter_call',
+                    adapter: adapterName,
+                    method: methodName,
+                    args,
+                    id
+                  });
+                });
+              };
+            }
+            globalThis.adapters[adapterName] = adapterObj;
+            globalThis[adapterName] = adapterObj;
+          }
+
+          __post({ type: 'ready' });
+        }
+
+        else if (type === 'adapter_result') {
+          const { id, result, error } = data;
+          const pending = pendingCalls.get(id);
+          if (pending) {
+            pendingCalls.delete(id);
+            if (error) {
+              // 'error' is the serialized DotCMSError shape ({ name, code, message, detail }).
+              // Rebuild a plain Error (class identity can't cross the boundary) but keep the
+              // code/name/detail so model code can branch on them.
+              const e = new Error(error.message);
+              if (error.name) e.name = error.name;
+              if (error.code) e.code = error.code;
+              if (error.detail) e.detail = error.detail;
+              pending.reject(e);
+            }
+            else pending.resolve(result);
+          }
+        }
+
+        else if (type === 'execute') {
+          try {
+            // Block dynamic import() — \`require\` is already removed, but \`import('node:fs')\`
+            // / \`import('node:net')\` would re-open filesystem/network access and bypass the
+            // adapter boundary. This is a source-level guard (matches the "confinement for
+            // trusted code generators" threat model; not hardened against deliberate obfuscation).
+            if (/\\bimport\\s*\\(/.test(data.code)) {
+              throw new Error('Dynamic import() is disabled in the sandbox; reach the host only through adapters.');
+            }
+            const AsyncFunction = Object.getPrototypeOf(async function(){}).constructor;
+            const fn = new AsyncFunction(data.code);
+            const result = await fn();
+            __post({ type: 'result', success: true, value: result, logs });
+          } catch (err) {
+            __post({
+              type: 'result',
+              success: false,
+              error: { name: err.name, message: err.message, code: err.code, detail: err.detail, stack: err.stack },
+              logs
+            });
+          }
+        }
+      });
+`;
+/**
+ * Build the full worker source for a backend. `bootstrap` defines `__post` / `__onMessage`
+ * (and, on Node, neutralizes `require`) before the shared harness body runs.
+ */
+function buildWorkerSource(bootstrap) {
+    return `${bootstrap}\n${HARNESS_BODY}`;
+}
+/** Node `worker_threads` bootstrap: transport via `parentPort`, plus `require` removal. */
+const NODE_WORKER_CODE = buildWorkerSource(`
+      const { parentPort } = require('worker_threads');
+      const __post = (m) => parentPort.postMessage(m);
+      const __onMessage = (handler) => parentPort.on('message', handler);
+      try {
+        Object.defineProperty(globalThis, 'require', { value: undefined, writable: false, configurable: false });
+      } catch { /* ignore */ }
+`);
+/** Bun / Web Worker bootstrap: transport via `self`. */
+const BUN_WORKER_CODE = buildWorkerSource(`
+      const __post = (m) => self.postMessage(m);
+      const __onMessage = (handler) => { self.onmessage = (event) => handler(event.data); };
+      try {
+        Object.defineProperty(globalThis, 'require', { value: undefined, writable: false, configurable: false });
+      } catch { /* ignore */ }
+`);
+/**
+ * Default per-execution resource caps, shared by both backends so a runaway/ballooning
+ * script can't exhaust the host. (Node applies these via `worker_threads.resourceLimits`;
+ * Bun applies what its Worker supports.)
+ */
+const DEFAULT_RESOURCE_LIMITS = {
+    maxOldGenerationSizeMb: 256,
+    maxYoungGenerationSizeMb: 32,
+    stackSizeMb: 4
+};
+
+const DEFAULT_CONFIG$1 = {
+    timeout: 5000,
+    globals: {},
+    // Kept for config parity with the Node backend; Bun's Web Worker cannot enforce these
+    // (no `resourceLimits` option), so they are advisory here — documented, not silently dropped.
+    resourceLimits: DEFAULT_RESOURCE_LIMITS
+};
+class BunWorkerSandbox {
+    constructor(config) {
+        this.config = { ...DEFAULT_CONFIG$1, ...config };
+    }
+    getConfig() {
+        return { ...this.config };
+    }
+    configure(config) {
+        this.config = { ...this.config, ...config };
+    }
+    async execute(code, context) {
+        const startTime = performance.now();
+        return new Promise((resolve) => {
+            const adapterMethods = {};
+            for (const [name, methods] of Object.entries(context.adapters)) {
+                adapterMethods[name] = Object.keys(methods);
+            }
+            const workerCode = BUN_WORKER_CODE;
+            const blob = new Blob([workerCode], { type: 'application/javascript' });
+            const url = URL.createObjectURL(blob);
+            const worker = new Worker(url);
+            let resolved = false;
+            const cleanup = () => {
+                if (!resolved) {
+                    resolved = true;
+                    worker.terminate();
+                    URL.revokeObjectURL(url);
+                    // Let the host abort any in-flight adapter work (threaded AbortSignal).
+                    this.config.onTeardown?.();
+                }
+            };
+            const timeoutId = setTimeout(() => {
+                if (!resolved) {
+                    cleanup();
+                    resolve({
+                        success: false,
+                        error: {
+                            name: 'TimeoutError',
+                            code: 'TIMEOUT',
+                            message: `Execution timed out after ${this.config.timeout}ms`
+                        },
+                        logs: [],
+                        executionTime: performance.now() - startTime
+                    });
+                }
+            }, this.config.timeout);
+            worker.onmessage = async (event) => {
+                const { type, ...data } = event.data;
+                if (type === 'ready') {
+                    worker.postMessage({ type: 'execute', data: { code } });
+                }
+                else if (type === 'adapter_call') {
+                    const { adapter, method, args, id } = data;
+                    // Posting to a worker that was already terminated (e.g. by a
+                    // timeout while this adapter call was in flight) throws and
+                    // would escape as an unhandled rejection, crashing the host.
+                    const postResult = (payload) => {
+                        if (resolved) {
+                            return;
+                        }
+                        try {
+                            worker.postMessage({ type: 'adapter_result', data: payload });
+                        }
+                        catch {
+                            /* worker gone — nothing to deliver the result to */
+                        }
+                    };
+                    try {
+                        const adapterObj = context.adapters[adapter];
+                        if (!adapterObj || !adapterObj[method]) {
+                            throw new Error(`Adapter method not found: ${adapter}.${method}`);
+                        }
+                        const result = await adapterObj[method](...args);
+                        postResult({ id, result });
+                    }
+                    catch (err) {
+                        // Send the serialized error (typed shape round-trips); drop `stack`
+                        // so host stacks don't cross into the sandbox.
+                        const error = errors.serializeError(err);
+                        delete error.stack;
+                        postResult({ id, error });
+                    }
+                }
+                else if (type === 'result') {
+                    clearTimeout(timeoutId);
+                    cleanup();
+                    const r = data;
+                    resolve({
+                        success: r.success,
+                        value: r.value,
+                        error: r.error,
+                        logs: r.logs || [],
+                        executionTime: performance.now() - startTime
+                    });
+                }
+            };
+            worker.onerror = (error) => {
+                clearTimeout(timeoutId);
+                cleanup();
+                resolve({
+                    success: false,
+                    error: {
+                        name: 'WorkerError',
+                        code: 'RUNTIME',
+                        message: error.message || 'Unknown worker error'
+                    },
+                    logs: [],
+                    executionTime: performance.now() - startTime
+                });
+            };
+            worker.postMessage({
+                type: 'init',
+                data: {
+                    variables: context.variables || {},
+                    adapterMethods,
+                    globals: this.config.globals
+                }
+            });
+        });
+    }
+    dispose() {
+        // Workers are created per execution, nothing to dispose
+    }
+}
+
+const DEFAULT_CONFIG = {
+    timeout: 5000,
+    globals: {},
+    resourceLimits: DEFAULT_RESOURCE_LIMITS
+};
+class NodeWorkerSandbox {
+    constructor(config) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+    }
+    getConfig() {
+        return { ...this.config };
+    }
+    configure(config) {
+        this.config = { ...this.config, ...config };
+    }
+    async execute(code, context) {
+        const startTime = performance.now();
+        return new Promise((resolve) => {
+            const adapterMethods = {};
+            for (const [name, methods] of Object.entries(context.adapters)) {
+                adapterMethods[name] = Object.keys(methods);
+            }
+            const workerCode = NODE_WORKER_CODE;
+            const limits = this.config.resourceLimits;
+            const worker = new node_worker_threads.Worker(workerCode, {
+                eval: true,
+                env: {},
+                resourceLimits: limits
+                    ? {
+                        maxOldGenerationSizeMb: limits.maxOldGenerationSizeMb,
+                        maxYoungGenerationSizeMb: limits.maxYoungGenerationSizeMb,
+                        stackSizeMb: limits.stackSizeMb
+                    }
+                    : undefined
+            });
+            let resolved = false;
+            const cleanup = () => {
+                if (!resolved) {
+                    resolved = true;
+                    worker.terminate();
+                    // Let the host abort any in-flight adapter work (threaded AbortSignal).
+                    this.config.onTeardown?.();
+                }
+            };
+            const timeoutId = setTimeout(() => {
+                if (!resolved) {
+                    cleanup();
+                    resolve({
+                        success: false,
+                        error: {
+                            name: 'TimeoutError',
+                            code: 'TIMEOUT',
+                            message: `Execution timed out after ${this.config.timeout}ms`
+                        },
+                        logs: [],
+                        executionTime: performance.now() - startTime
+                    });
+                }
+            }, this.config.timeout);
+            worker.on('message', async (msg) => {
+                const { type, ...data } = msg;
+                if (type === 'ready') {
+                    worker.postMessage({ type: 'execute', data: { code } });
+                }
+                else if (type === 'adapter_call') {
+                    const { adapter, method, args, id } = data;
+                    // Posting to a worker that was already terminated (e.g. by a
+                    // timeout while this adapter call was in flight) throws and
+                    // would escape as an unhandled rejection, crashing the host.
+                    const postResult = (payload) => {
+                        if (resolved) {
+                            return;
+                        }
+                        try {
+                            worker.postMessage({ type: 'adapter_result', data: payload });
+                        }
+                        catch {
+                            /* worker gone — nothing to deliver the result to */
+                        }
+                    };
+                    try {
+                        const adapterObj = context.adapters[adapter];
+                        if (!adapterObj || !adapterObj[method]) {
+                            throw new Error(`Adapter method not found: ${adapter}.${method}`);
+                        }
+                        const result = await adapterObj[method](...args);
+                        postResult({ id, result });
+                    }
+                    catch (err) {
+                        // Send the serialized error (name + code + detail) so the typed shape
+                        // round-trips the boundary. Drop `stack` — the worker rebuilds a fresh
+                        // Error and never reads it, and host stacks shouldn't cross into the sandbox.
+                        const error = errors.serializeError(err);
+                        delete error.stack;
+                        postResult({ id, error });
+                    }
+                }
+                else if (type === 'result') {
+                    clearTimeout(timeoutId);
+                    cleanup();
+                    const r = data;
+                    resolve({
+                        success: r.success,
+                        value: r.value,
+                        error: r.error,
+                        logs: r.logs || [],
+                        executionTime: performance.now() - startTime
+                    });
+                }
+            });
+            worker.on('error', (error) => {
+                clearTimeout(timeoutId);
+                cleanup();
+                resolve({
+                    success: false,
+                    error: {
+                        name: 'WorkerError',
+                        code: 'RUNTIME',
+                        message: error.message || 'Unknown worker error'
+                    },
+                    logs: [],
+                    executionTime: performance.now() - startTime
+                });
+            });
+            worker.postMessage({
+                type: 'init',
+                data: {
+                    variables: context.variables || {},
+                    adapterMethods,
+                    globals: this.config.globals
+                }
+            });
+        });
+    }
+    dispose() {
+        // Workers are created per execution, nothing to dispose
+    }
+}
+
+/**
+ * Low-level worker-sandbox factory. Auto-detects the runtime: native Web Workers on Bun,
+ * `worker_threads` on Node. Returns the raw {@link ISandbox} whose `execute(code, context)`
+ * the {@link Executor} drives. Most callers want the higher-level `createSandbox` barrel
+ * export (which returns a `run(code)` surface) instead of this.
+ *
+ * Backends are statically imported (not `require`d) so this works in both the ESM and CJS
+ * builds — `require` is undefined in an ESM module. Importing both is cheap: each file only
+ * declares a class, and `node:worker_threads` (used by the Node backend) is available on Bun too.
+ */
+function createWorkerSandbox(config) {
+    if (typeof globalThis.Bun !== 'undefined') {
+        return new BunWorkerSandbox(config);
+    }
+    return new NodeWorkerSandbox(config);
+}
+
+class Executor {
+    constructor(options = {}) {
+        this.adapters = new Map();
+        this.sandboxConfig = options.config?.sandbox ?? {
+            timeout: 5000,
+            globals: {}
+        };
+        this.sandboxFactory = options.sandboxFactory ?? createWorkerSandbox;
+        if (options.config?.adapters) {
+            for (const adapter of options.config.adapters) {
+                this.registerAdapter(adapter);
+            }
+        }
+    }
+    registerAdapter(adapter) {
+        this.adapters.set(adapter.name, adapter);
+    }
+    unregisterAdapter(name) {
+        return this.adapters.delete(name);
+    }
+    getAdapter(name) {
+        return this.adapters.get(name);
+    }
+    getAdapterNames() {
+        return Array.from(this.adapters.keys());
+    }
+    async execute(code, options = {}) {
+        const sandboxConfig = {
+            ...this.sandboxConfig,
+            ...options.sandbox
+        };
+        const sandbox = this.sandboxFactory(sandboxConfig);
+        try {
+            const context = this.buildExecutionContext(options.adapters, options.variables);
+            return await sandbox.execute(code, context);
+        }
+        finally {
+            sandbox.dispose();
+        }
+    }
+    configureSandbox(config) {
+        this.sandboxConfig = {
+            ...this.sandboxConfig,
+            ...config
+        };
+    }
+    buildExecutionContext(adapterNames, variables) {
+        const adaptersToInclude = adapterNames
+            ? adapterNames.filter((name) => this.adapters.has(name))
+            : Array.from(this.adapters.keys());
+        const adapterMethods = {};
+        for (const name of adaptersToInclude) {
+            const adapter = this.adapters.get(name);
+            if (!adapter)
+                continue;
+            adapterMethods[name] = {};
+            for (const [methodName, method] of adapter.methods) {
+                adapterMethods[name][methodName] = method.execute.bind(method);
+            }
+        }
+        return {
+            adapters: adapterMethods,
+            variables
+        };
+    }
+}
+function createExecutor(options) {
+    return new Executor(options);
+}
+
+function validateInput(methodName, schema, raw) {
+    const result = schema.safeParse(raw);
+    if (!result.success) {
+        throw new errors.ValidationError(`Invalid arguments for "${methodName}": ${result.error.message}`, result.error.issues);
+    }
+    return result.data;
+}
+function validateOutput(schema, value) {
+    if (!schema)
+        return value;
+    const result = schema.safeParse(value);
+    if (!result.success) {
+        // Output drift is a contract problem, not untrusted input — surface it as a
+        // validation error so a dotCMS response change shows up at the boundary rather
+        // than as a silent `undefined` downstream.
+        throw new errors.ValidationError(`Adapter result did not match its output schema: ${result.error.message}`, result.error.issues);
+    }
+    return result.data;
+}
+/**
+ * Build a typed, schema-validated adapter. Handlers get `(input, ctx)` — `input` already
+ * validated, `ctx.request` already auth-bound by the runtime.
+ *
+ * The returned value is a plain `Adapter` (the `methods` Map is populated with thunks that
+ * throw until `withContext` is called), so it can be wrapped (e.g. by an allow-list) before
+ * it reaches the runtime, exactly like the built-in `dotcmsAdapter`.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function defineAdapter(def) {
+    const schemas = {};
+    let modelExposable = true;
+    for (const [methodName, m] of Object.entries(def.methods)) {
+        schemas[methodName] = { description: m.description, input: m.input, output: m.output };
+        if (!m.output)
+            modelExposable = false;
+    }
+    const makeMethods = (ctx) => {
+        const methods = new Map();
+        for (const [methodName, m] of Object.entries(def.methods)) {
+            methods.set(methodName, {
+                name: methodName,
+                description: m.description,
+                parameters: [
+                    {
+                        name: 'input',
+                        type: 'object',
+                        description: m.description,
+                        required: true
+                    }
+                ],
+                async execute(...args) {
+                    if (!ctx) {
+                        throw new errors.ValidationError(`Adapter "${def.name}" was used without a bound context. ` +
+                            `Call adapter.withContext(ctx) before running it.`);
+                    }
+                    const input = validateInput(methodName, m.input, args[0]);
+                    const result = await m.handler(input, ctx);
+                    return validateOutput(m.output, result);
+                }
+            });
+        }
+        return methods;
+    };
+    const base = {
+        name: def.name,
+        description: def.description,
+        version: def.version ?? '1.0.0',
+        methods: makeMethods(),
+        __defined: true,
+        __schemas: schemas,
+        modelExposable,
+        withContext(ctx) {
+            return {
+                name: def.name,
+                description: def.description,
+                version: def.version ?? '1.0.0',
+                methods: makeMethods(ctx)
+            };
+        }
+    };
+    return base;
+}
+/** Type guard: distinguishes a `defineAdapter` result from a hand-built `Adapter`. */
+function isDefinedAdapter(adapter) {
+    return adapter.__defined === true;
+}
+/**
+ * Render a defined adapter's methods as JSON-Schema-ish tool definitions an LLM can consume.
+ * This is the bridge to MCP / tool-calling: the declared Zod schemas become the tool's
+ * input/output contract, replacing hand-written description prose.
+ *
+ * Only methods that declare an `output` schema are emitted — a method without one is treated
+ * as internal plumbing and withheld from the model.
+ */
+function describeAdapterForLLM(adapter) {
+    const tools = [];
+    for (const [methodName, s] of Object.entries(adapter.__schemas)) {
+        if (!s.output)
+            continue; // internal-only method — not model-exposable
+        tools.push({
+            name: `${adapter.name}.${methodName}`,
+            description: s.description,
+            inputSchema: zod.z.toJSONSchema(s.input),
+            outputSchema: zod.z.toJSONSchema(s.output)
+        });
+    }
+    return tools;
+}
+
+/**
+ * Default hard cap on the string handed back to the model (~6k tokens). A depth-1/2
+ * `resolveRef` of even the largest schemas fits comfortably; a whole-`spec` dump does not.
+ */
+const DEFAULT_MAX_CHARS = 25_000;
+/**
+ * Render a {@link SandboxResult} into the single string a tool hands back to the model, and
+ * hard-cap its length so one query can't flood the context window.
+ *
+ * There is NO truncation anywhere else on the result path — whatever the model's code returns is
+ * stringified whole. This is the one place that bounds it. The cap is applied to the final
+ * combined string in BOTH the success and error branches (an `HttpError` body embedded in an
+ * error message can itself be huge). On truncation, a clear notice explains the cut and tells the
+ * model how to narrow the query rather than silently dropping data.
+ */
+function formatSandboxResult(result, options) {
+    const maxChars = options?.maxChars ?? DEFAULT_MAX_CHARS;
+    let out;
+    if (!result.success) {
+        const errorMsg = result.error
+            ? `${result.error.name}: ${result.error.message}`
+            : 'Unknown error';
+        const logs = result.logs.length > 0 ? `\nLogs:\n${result.logs.join('\n')}` : '';
+        out = `Error: ${errorMsg}${logs}`;
+    }
+    else {
+        // Logs are built BEFORE the value is stringified. Serialization can fail (see
+        // `stringifyValue`), and when it did, the throw escaped this function with the logs
+        // still unattached — so every `console.log` the model had written to debug its code
+        // was discarded at the exact moment it became most useful.
+        const logs = result.logs.length > 0 ? `\n\n--- Logs ---\n${result.logs.join('\n')}` : '';
+        const value = typeof result.value === 'string' ? result.value : stringifyValue(result.value);
+        out = `${value}${logs}`;
+    }
+    if (out.length <= maxChars)
+        return out;
+    const hint = options?.truncationHint ? ` ${options.truncationHint}` : '';
+    return (out.slice(0, maxChars) +
+        `\n\n[output truncated at ${maxChars} of ${out.length} chars — refine the query: ` +
+        `select specific paths/fields, use pick()/first(), or resolve one schema at a time.${hint}]`);
+}
+/**
+ * `JSON.stringify` for a value that arrived over `postMessage`.
+ *
+ * The two serializers do NOT agree on what is representable. `postMessage` uses structured
+ * clone, which handles circular references and `BigInt`; JSON handles neither. So a worker
+ * could report `success: true`, the value could transfer intact, and stringifying it here
+ * would then throw `TypeError: Converting circular structure to JSON` — out of a function
+ * whose job is to REPORT the result. It presented as "the tool breaks only when my code
+ * succeeds", which is about the worst shape a failure can take.
+ *
+ * Circular references are not exotic here: building a tree from a flat folder or page list
+ * with parent back-pointers is the ordinary way to do it. They are replaced with a marker
+ * rather than dropped, so the model can see the shape it produced and why it could not be
+ * returned whole.
+ */
+function stringifyValue(value) {
+    try {
+        return JSON.stringify(value, circularSafeReplacer(), 2) ?? String(value);
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        return (`[value could not be serialized: ${reason}]\n` +
+            `The worker returned this value successfully, but it cannot be represented as JSON. ` +
+            `Return a plain-data projection instead — e.g. pick(items, ['id','title']) — rather ` +
+            `than the object graph itself.`);
+    }
+}
+/** A replacer that survives cycles and BigInt, the two structured-clone/JSON mismatches. */
+function circularSafeReplacer() {
+    const seen = new WeakSet();
+    return function replacer(_key, value) {
+        if (typeof value === 'bigint') {
+            // BigInt has no JSON representation at all — stringify throws on it outright.
+            return `${value.toString()}n`;
+        }
+        if (typeof value === 'object' && value !== null) {
+            if (seen.has(value)) {
+                return '[Circular]';
+            }
+            seen.add(value);
+        }
+        return value;
+    };
+}
+
+exports.Executor = Executor;
+exports.createExecutor = createExecutor;
+exports.createWorkerSandbox = createWorkerSandbox;
+exports.defineAdapter = defineAdapter;
+exports.describeAdapterForLLM = describeAdapterForLLM;
+exports.formatSandboxResult = formatSandboxResult;
+exports.isDefinedAdapter = isDefinedAdapter;