@dotcms/ai 0.1.0

package/src/adapter/context-cache.d.ts

@@ -0,0 +1,35 @@
+import { type DotCMSContext } from './context';
+import type { Adapter } from '../sandbox/types';
+interface CacheOptions {
+    ttlMs?: number;
+    onError?: (label: string, error: unknown) => void;
+    now?: () => number;
+}
+/**
+ * Cache for dotCMS instance context, keyed on `(sessionId, url)`.
+ * - TTL-based expiry (default 5 minutes)
+ * - In-flight dedup so concurrent loads for the same key run once
+ * - In-memory only; no persistence
+ */
+export declare class ContextCache {
+    private cache;
+    private inFlight;
+    private ttlMs;
+    private onError?;
+    private now;
+    constructor(options?: CacheOptions);
+    /**
+     * Get (or load) the instance context for `(sessionId, url)`. `url` MUST be the dotCMS
+     * base URL the `apiAdapter` is bound to — it is folded into the cache key so two tenants
+     * sharing a `sessionId` never collide.
+     */
+    get(sessionId: string, url: string, apiAdapter: Adapter): Promise<DotCMSContext>;
+    invalidate(sessionId: string, url: string): void;
+    clear(): void;
+}
+/**
+ * Shared cache instance. Prefer letting the runtime own its own `ContextCache` (the front
+ * door does); this module-level singleton remains for low-level callers that opt into it.
+ */
+export declare function getSharedContextCache(options?: CacheOptions): ContextCache;
+export {};

package/src/adapter/context.d.ts

@@ -0,0 +1,42 @@
+import type { Adapter } from '../sandbox/types';
+export interface ContentTypeSummary {
+    id: string;
+    name: string;
+    variable: string;
+    baseType: string;
+    host?: string;
+    folder?: string;
+}
+export interface SiteSummary {
+    identifier: string;
+    hostname: string;
+    isDefault: boolean;
+    archived: boolean;
+}
+export interface LanguageSummary {
+    id: number;
+    languageCode: string;
+    countryCode: string;
+    language: string;
+    country: string;
+    isoCode: string;
+}
+export interface CurrentUserSummary {
+    userId: string;
+    email: string;
+    givenName?: string;
+    surname?: string;
+    admin: boolean;
+    roles?: string[];
+}
+export interface DotCMSContext {
+    contentTypes: ContentTypeSummary[];
+    sites: SiteSummary[];
+    languages: LanguageSummary[];
+    currentUser: CurrentUserSummary | null;
+}
+/**
+ * Load a minimal snapshot of dotCMS instance context for sandbox injection.
+ * Each loader is independent — a failure in one does not poison the others.
+ */
+export declare function loadDotCMSContext(apiAdapter: Adapter, onError?: (label: string, error: unknown) => void): Promise<DotCMSContext>;

package/src/adapter/http-client.d.ts

@@ -0,0 +1,37 @@
+import { type RequestCallEvent, type RequestOptions, type RequestPolicy } from './request-core';
+import type { Adapter } from '../sandbox/types';
+export { type BinaryResponseEnvelope, type RequestOptions, type RequestPolicy, type RequestCallEvent, isBinaryResponseEnvelope } from './request-core';
+export interface ApiAdapterConfig {
+    dotcmsUrl: string;
+    authToken: string;
+    /** Optional policy/allow-list consulted before each request reaches the wire. */
+    policy?: RequestPolicy;
+    /** Aborts in-flight requests when the surrounding execution (e.g. the sandbox) is torn down. */
+    signal?: AbortSignal;
+    /** Observability hook fired around each call (token/sensitive bodies never included). */
+    onCall?: (event: RequestCallEvent) => void;
+}
+/**
+ * Create the "api" adapter for making authenticated HTTP calls to dotCMS.
+ *
+ * This is the dotCMS door out of the sandbox. The adapter's single `request` method is a
+ * thin wrapper over the shared {@link requestCore} — so a request driven by the sandboxed
+ * `api.request` and one driven by the runtime's direct `request()` are byte-for-byte the
+ * same code path (one auth path, one allow-list, one error model). Auth tokens are injected
+ * by the host — never exposed to the sandbox.
+ */
+export declare function createApiAdapter(config: ApiAdapterConfig): Adapter;
+/**
+ * The dotCMS adapter — the building block exported from `@dotcms/ai/adapter`.
+ *
+ * Returns both the underlying {@link Adapter} (for the sandbox) and a direct `request`
+ * function (the no-worker path). A power-user can wrap this value — e.g. with an allow-list —
+ * before handing it to the runtime, because it is a plain object you can compose.
+ */
+export interface DotCMSAdapter {
+    /** The adapter object the sandbox executor consumes (`api.request` inside sandbox code). */
+    adapter: Adapter;
+    /** The direct, no-worker request path — the same shared core the sandbox bridges to. */
+    request(options: RequestOptions): Promise<unknown>;
+}
+export declare function dotcmsAdapter(config: ApiAdapterConfig): DotCMSAdapter;

package/src/adapter/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `@dotcms/ai/adapter` — the dotCMS-specific building blocks: the dotCMS door out of the
+ * sandbox (`dotcmsAdapter` / `createApiAdapter`), the shared request core, instance-context
+ * loading, and the context cache. dotCMS-wired by design (the generic engine is `/sandbox`).
+ */
+export { createApiAdapter, dotcmsAdapter, isBinaryResponseEnvelope } from './http-client';
+export type { ApiAdapterConfig, DotCMSAdapter, BinaryResponseEnvelope, RequestOptions, RequestPolicy, RequestCallEvent } from './http-client';
+export { requestCore } from './request-core';
+export type { RequestCoreContext } from './request-core';
+export { loadDotCMSContext } from './context';
+export type { DotCMSContext, ContentTypeSummary, SiteSummary, LanguageSummary, CurrentUserSummary } from './context';
+export { ContextCache, getSharedContextCache } from './context-cache';

package/src/adapter/request-core.d.ts

@@ -0,0 +1,77 @@
+/**
+ * The single shared request core.
+ *
+ * "One adapter, one auth path, one allow-list" is only true if BOTH verbs of the runtime
+ * route through one function that owns *all* of: path/method validation, the policy check,
+ * auth injection, `fetch`, response decoding (incl. the binary envelope), the error model,
+ * and abort/timeout. `runtime.request()` calls `requestCore` directly; the sandbox's
+ * `api.request` is a thin worker→host bridge to this same function. Neither verb may add
+ * behavior the other lacks — that is the contract, not an aspiration.
+ */
+interface FileFieldDescriptor {
+    name: string;
+    type: string;
+    data?: string;
+    url?: string;
+}
+type FormDataFieldValue = string | FileFieldDescriptor;
+export interface RequestOptions {
+    method?: string;
+    path: string;
+    query?: Record<string, string | number | boolean>;
+    body?: unknown;
+    formData?: Record<string, FormDataFieldValue>;
+    headers?: Record<string, string>;
+    responseType?: 'auto' | 'base64';
+}
+/**
+ * A policy hook consulted before a request reaches the wire. Return `false` (or throw) to
+ * reject. The single place a caller-owned allow-list plugs in — both verbs honor it because
+ * both flow through `requestCore`.
+ */
+export type RequestPolicy = (req: {
+    method: string;
+    path: string;
+}) => boolean | void;
+/** Host-side context the request core needs. Auth lives here, never in the caller's code. */
+export interface RequestCoreContext {
+    baseUrl: string;
+    authToken: string;
+    /** Optional policy/allow-list consulted before every call. */
+    policy?: RequestPolicy;
+    /** Aborts the in-flight fetch when the surrounding execution (e.g. sandbox) is torn down. */
+    signal?: AbortSignal;
+    /** Observability hook — fired around each call with redacted metadata (never the token). */
+    onCall?: (event: RequestCallEvent) => void;
+}
+export interface RequestCallEvent {
+    method: string;
+    path: string;
+    status?: number;
+    durationMs: number;
+    ok: boolean;
+    errorCode?: string;
+}
+/**
+ * Tagged envelope returned for non-textual response bodies. The raw bytes are
+ * base64-encoded so they survive the `JSON.stringify` serialization boundary in
+ * the consuming sandbox intact — `response.text()` would corrupt any non-UTF-8 byte
+ * into the U+FFFD replacement char. Consumers detect `__dotcmsBinary` and decode.
+ */
+export interface BinaryResponseEnvelope {
+    __dotcmsBinary: true;
+    contentType: string;
+    base64: string;
+    byteLength: number;
+}
+/**
+ * Type guard for the binary response envelope. Consumers can use this to detect
+ * a binary body and `Buffer.from(envelope.base64, 'base64')` to recover the bytes.
+ */
+export declare function isBinaryResponseEnvelope(value: unknown): value is BinaryResponseEnvelope;
+/**
+ * Execute one authenticated request against dotCMS. This is the function both verbs share.
+ * Auth is injected here, on the host side; the executing code never sees the token.
+ */
+export declare function requestCore(options: RequestOptions, ctx: RequestCoreContext): Promise<unknown>;
+export {};

package/src/runtime.d.ts

@@ -0,0 +1,70 @@
+import { type RequestCallEvent, type RequestOptions, type RequestPolicy } from './adapter/request-core';
+import type { DotCMSContext } from './adapter/context';
+import type { SandboxResult } from './sandbox/types';
+/**
+ * Policy controlling which requests are permitted. Either a list of allowed path prefixes
+ * (a request is allowed if its path starts with any entry) or a predicate consulted per call.
+ * Both verbs honor it, because both flow through the one shared request core.
+ */
+export type RuntimeAllow = string[] | RequestPolicy;
+export interface DotCMSRuntimeConfig {
+    /** dotCMS instance URL. */
+    url: string;
+    /** Server-side token. NEVER enters the sandbox — injected host-side on every call. */
+    token: string;
+    /** Optional allow-list / policy applied to every request. */
+    allow?: RuntimeAllow;
+    /** Context-cache + isolation key. Defaults to `__default__`. */
+    sessionId?: string;
+    /** Inject the OpenAPI `spec` global into `run(code)` (the search use case). */
+    includeSpec?: boolean;
+    /** Sandbox wall-clock timeout (ms) for `run(code)`. Defaults to 15000. */
+    timeout?: number;
+    /** Observability hook fired around each request (token/sensitive bodies never logged). */
+    onCall?: (event: RequestCallEvent) => void;
+    /** Error handler for instance-context load failures (per loader). */
+    onContextError?: (label: string, error: unknown) => void;
+    /**
+     * Whether to leak stack traces (which can contain host paths) to executed/model code.
+     * Defaults to false — stacks are withheld from `run(code)` results.
+     */
+    includeStacks?: boolean;
+}
+export interface DotCMSRuntime {
+    /**
+     * DIRECT — you write the call. No worker. Use this whenever you author the call yourself.
+     * Routes through the same shared request core as `run`. Pass `opts.signal` to make the
+     * call abortable (e.g. to wrap it in your own timeout) — the direct path has no surrounding
+     * timeout of its own.
+     */
+    request(options: RequestOptions, opts?: {
+        signal?: AbortSignal;
+    }): Promise<unknown>;
+    /**
+     * SANDBOXED — runs `code` you did NOT write (a model did) in a confined worker whose
+     * `api.request` forwards to the same request core. Returns the structured sandbox result.
+     */
+    run<T = unknown>(code: string): Promise<SandboxResult<T>>;
+    /** Load (or read cached) instance context for this runtime's session+url. */
+    loadContext(): Promise<DotCMSContext>;
+}
+/**
+ * The front door. One runtime, two verbs.
+ *
+ * `request` is the default — use it when you write the call. `run` is only for code you did
+ * not write (a model did). `run(code)` is implemented *as* "spin a worker whose `api.request`
+ * forwards to this runtime's request core", so the two verbs cannot drift: one is built on
+ * the other, sharing one adapter, one auth path, one allow-list, one error model.
+ *
+ * Note: this is an execution runtime, not an agent. There is no LLM, no inference, no
+ * prompting inside it. The agent is what the *user* builds on top.
+ */
+export declare function createRuntime(config: DotCMSRuntimeConfig): DotCMSRuntime;
+export { defineAdapter, describeAdapterForLLM } from './sandbox/define-adapter';
+export type { AdapterContext, AdapterDef, AdapterMethodDef, DefinedAdapter } from './sandbox/define-adapter';
+export { DotCMSError, ValidationError, PolicyError, HttpError, TimeoutError, AbortError, SandboxError, RuntimeError, isDotCMSError, serializeError } from './sandbox/errors';
+export type { DotCMSErrorCode, SerializedDotCMSError } from './sandbox/errors';
+export type { SandboxResult, SandboxResultError } from './sandbox/types';
+export { isBinaryResponseEnvelope } from './adapter/request-core';
+export type { BinaryResponseEnvelope, RequestOptions, RequestCallEvent } from './adapter/request-core';
+export type { DotCMSContext, ContentTypeSummary, SiteSummary, LanguageSummary, CurrentUserSummary } from './adapter/context';

package/src/sandbox/bun-worker.d.ts

@@ -0,0 +1,10 @@
+import type { ISandbox } from './interface';
+import type { ExecutionContext, SandboxConfig, SandboxResult } from './types';
+export declare class BunWorkerSandbox implements ISandbox {
+    private config;
+    constructor(config?: SandboxConfig);
+    getConfig(): SandboxConfig;
+    configure(config: Partial<SandboxConfig>): void;
+    execute<T = unknown>(code: string, context: ExecutionContext): Promise<SandboxResult<T>>;
+    dispose(): void;
+}

package/src/sandbox/define-adapter.d.ts

@@ -0,0 +1,88 @@
+import { z } from 'zod';
+import type { Adapter } from './types';
+/**
+ * The host capabilities the runtime injects into every adapter handler. `request` is the
+ * shared request core with auth already bound — a handler reaches dotCMS through it, never
+ * through a free-floating global. `signal` aborts in-flight work when the sandbox times out.
+ */
+export interface AdapterContext {
+    request: (opts: RequestLike) => Promise<unknown>;
+    signal?: AbortSignal;
+}
+/**
+ * Minimal request shape an adapter handler passes to `ctx.request`. Kept structural (not a
+ * hard import of the dotCMS RequestOptions) so `/sandbox` stays free of dotCMS specifics.
+ */
+export interface RequestLike {
+    method?: string;
+    path: string;
+    query?: Record<string, string | number | boolean>;
+    body?: unknown;
+    formData?: Record<string, unknown>;
+    headers?: Record<string, string>;
+    responseType?: 'auto' | 'base64';
+}
+/**
+ * A single method definition on an adapter. `input` is mandatory — it is the *trust*
+ * boundary: arguments arrive from model-authored code inside the sandbox and must be
+ * validated before the handler runs. `output` is the *tool-contract* boundary: required for
+ * any model-facing adapter (it becomes the result schema the LLM plans against), optional
+ * only for internal host-to-host plumbing the model never sees.
+ */
+export interface AdapterMethodDef<TInput extends z.ZodTypeAny = z.ZodTypeAny, TOutput extends z.ZodTypeAny = z.ZodTypeAny> {
+    description: string;
+    input: TInput;
+    output?: TOutput;
+    handler: (input: z.infer<TInput>, ctx: AdapterContext) => Promise<unknown> | unknown;
+}
+export interface AdapterDef<TMethods extends Record<string, AdapterMethodDef<any, any>> = Record<string, AdapterMethodDef<any, any>>> {
+    name: string;
+    description?: string;
+    version?: string;
+    methods: TMethods;
+}
+/**
+ * A defined adapter. It IS a plain `Adapter` (so the executor consumes it unchanged) plus:
+ *  - `__schemas`: the per-method Zod input/output, used to auto-generate tool definitions;
+ *  - `withContext(ctx)`: binds the injected host capabilities, returning a runnable adapter.
+ *
+ * The schemas being declared is what lets the runtime *describe the adapter to an LLM
+ * automatically* — that declaration IS the tool definition (the bridge to MCP/tool-calling).
+ */
+export interface DefinedAdapter extends Adapter {
+    readonly __defined: true;
+    readonly __schemas: Record<string, {
+        description: string;
+        input: z.ZodTypeAny;
+        output?: z.ZodTypeAny;
+    }>;
+    /** Every method declares an `output` schema → safe to expose to a model. */
+    readonly modelExposable: boolean;
+    /** Bind host capabilities (the injected `ctx`) and return a runnable adapter. */
+    withContext(ctx: AdapterContext): Adapter;
+}
+/**
+ * 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`.
+ */
+export declare function defineAdapter<TMethods extends Record<string, AdapterMethodDef<any, any>>>(def: AdapterDef<TMethods>): DefinedAdapter;
+/** Type guard: distinguishes a `defineAdapter` result from a hand-built `Adapter`. */
+export declare function isDefinedAdapter(adapter: Adapter): adapter is DefinedAdapter;
+/**
+ * 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.
+ */
+export declare function describeAdapterForLLM(adapter: DefinedAdapter): Array<{
+    name: string;
+    description: string;
+    inputSchema: unknown;
+    outputSchema?: unknown;
+}>;

package/src/sandbox/errors.d.ts

@@ -0,0 +1,91 @@
+/**
+ * The single typed error hierarchy for `@dotcms/ai`.
+ *
+ * Both verbs of the runtime — `request()` (direct) and `run()` (sandboxed) — surface
+ * the *same* error types, because both route through one shared request core. The
+ * model-facing string an MCP tool builds is *formatting on top of* these errors, not a
+ * separate error model.
+ *
+ * Every error carries a stable, machine-readable `code` and a `toJSON()` so it survives
+ * the worker→host serialization boundary (a thrown error becomes `{ name, message, stack }`
+ * by default; these types preserve `code` and the structured detail too).
+ */
+export type DotCMSErrorCode = 'VALIDATION' | 'POLICY' | 'HTTP' | 'TIMEOUT' | 'ABORT' | 'SANDBOX' | 'RUNTIME';
+/** Serializable shape every DotCMSError flattens to (and that crosses the worker boundary). */
+export interface SerializedDotCMSError {
+    name: string;
+    code: DotCMSErrorCode;
+    message: string;
+    /**
+     * Present only when `includeStack` is enabled on the runtime. Host stack traces can
+     * contain absolute host paths, so they are withheld from model-authored code by default.
+     */
+    stack?: string;
+    /** Type-specific structured detail (HTTP status + body, validation issues, etc.). */
+    detail?: Record<string, unknown>;
+}
+export declare abstract class DotCMSError extends Error {
+    abstract readonly code: DotCMSErrorCode;
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+    /** Type-specific structured detail; overridden by subclasses that carry data. */
+    detail(): Record<string, unknown> | undefined;
+    toJSON(): SerializedDotCMSError;
+}
+/** Adapter input failed validation, or request options were malformed. */
+export declare class ValidationError extends DotCMSError {
+    readonly code: "VALIDATION";
+    /** Field-level issues, when the source was a Zod (or similar) schema. */
+    readonly issues?: unknown[];
+    constructor(message: string, issues?: unknown[]);
+    detail(): Record<string, unknown> | undefined;
+}
+/** The allow-list / policy rejected the call before it reached the network. */
+export declare class PolicyError extends DotCMSError {
+    readonly code: "POLICY";
+    readonly method: string;
+    readonly path: string;
+    constructor(message: string, method: string, path: string);
+    detail(): Record<string, unknown>;
+}
+/** dotCMS responded with a non-2xx status. Carries the status and the (text) body. */
+export declare class HttpError extends DotCMSError {
+    readonly code: "HTTP";
+    readonly status: number;
+    readonly statusText: string;
+    readonly body: string;
+    constructor(status: number, statusText: string, body: string);
+    detail(): Record<string, unknown>;
+}
+/** A timeout elapsed (sandbox wall-clock, per-adapter-call, or context load). */
+export declare class TimeoutError extends DotCMSError {
+    readonly code: "TIMEOUT";
+    readonly timeoutMs?: number;
+    constructor(message: string, timeoutMs?: number);
+    detail(): Record<string, unknown> | undefined;
+}
+/** The call was aborted in-flight (typically because the sandbox timed out). */
+export declare class AbortError extends DotCMSError {
+    readonly code: "ABORT";
+}
+/** Model-authored code threw while executing inside the sandbox. */
+export declare class SandboxError extends DotCMSError {
+    readonly code: "SANDBOX";
+    /** The original error's name (e.g. "TypeError") as seen inside the sandbox. */
+    readonly originalName?: string;
+    constructor(message: string, originalName?: string, stack?: string);
+    detail(): Record<string, unknown> | undefined;
+}
+/** Catch-all for runtime-internal failures that don't fit a more specific type. */
+export declare class RuntimeError extends DotCMSError {
+    readonly code: "RUNTIME";
+}
+/** Type guard for any error in the hierarchy. */
+export declare function isDotCMSError(value: unknown): value is DotCMSError;
+/**
+ * Normalize any thrown value into a serializable error shape. Used at the worker→host
+ * boundary and when formatting a result, so callers always get a consistent structure
+ * regardless of what was thrown.
+ */
+export declare function serializeError(value: unknown): SerializedDotCMSError;

package/src/sandbox/executor.d.ts

@@ -0,0 +1,27 @@
+import type { ISandbox } from './interface';
+import type { Adapter, SandboxConfig, SandboxResult } from './types';
+export interface ExecutorOptions {
+    config?: {
+        adapters?: Adapter[];
+        sandbox?: SandboxConfig;
+    };
+    sandboxFactory?: (config?: SandboxConfig) => ISandbox;
+}
+export declare class Executor {
+    private adapters;
+    private sandboxConfig;
+    private sandboxFactory;
+    constructor(options?: ExecutorOptions);
+    registerAdapter(adapter: Adapter): void;
+    unregisterAdapter(name: string): boolean;
+    getAdapter(name: string): Adapter | undefined;
+    getAdapterNames(): string[];
+    execute<T = unknown>(code: string, options?: {
+        sandbox?: Partial<SandboxConfig>;
+        adapters?: string[];
+        variables?: Record<string, unknown>;
+    }): Promise<SandboxResult<T>>;
+    configureSandbox(config: Partial<SandboxConfig>): void;
+    private buildExecutionContext;
+}
+export declare function createExecutor(options?: ExecutorOptions): Executor;

package/src/sandbox/factory.d.ts

@@ -0,0 +1,13 @@
+import type { ISandbox } from './interface';
+import type { SandboxConfig } from './types';
+/**
+ * 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.
+ */
+export declare function createWorkerSandbox(config?: SandboxConfig): ISandbox;

package/src/sandbox/index.d.ts

@@ -0,0 +1,44 @@
+/**
+ * `@dotcms/ai/sandbox` — the generic execution engine. ZERO dotCMS code lives here (a
+ * lint-enforced module boundary); this subpath is fully generic. The dotCMS wiring lives in
+ * `@dotcms/ai/adapter`, and the front door that combines them in `@dotcms/ai`.
+ */
+import { type RequestLike } from './define-adapter';
+import type { Adapter, SandboxResourceLimits, SandboxResult } from './types';
+export { Executor, createExecutor } from './executor';
+export type { ExecutorOptions } from './executor';
+export { createWorkerSandbox } from './factory';
+export type { ISandbox, SandboxFactory } from './interface';
+export { defineAdapter, isDefinedAdapter, describeAdapterForLLM } from './define-adapter';
+export type { AdapterContext, AdapterDef, AdapterMethodDef, DefinedAdapter, RequestLike } from './define-adapter';
+export { DotCMSError, ValidationError, PolicyError, HttpError, TimeoutError, AbortError, SandboxError, RuntimeError, isDotCMSError, serializeError } from './errors';
+export type { DotCMSErrorCode, SerializedDotCMSError } from './errors';
+export type { Adapter, AdapterMethod, AdapterMethodParameter, SandboxConfig, SandboxResourceLimits, SandboxResult, SandboxResultError, ExecutionContext } from './types';
+export interface CreateSandboxConfig {
+    /** Adapters granted to the sandboxed code — the only doors out. */
+    adapters: Adapter[];
+    /** Wall-clock timeout (ms). */
+    timeout?: number;
+    /** Extra globals injected into the sandbox. */
+    globals?: Record<string, unknown>;
+    /** Per-execution memory/stack caps. */
+    resourceLimits?: SandboxResourceLimits;
+    /**
+     * Host `request` capability injected into `defineAdapter` handlers as `ctx.request`. When
+     * provided, defined adapters are bound to it (and the per-run abort signal) before running.
+     * For the generic engine this is optional; the dotCMS front door always provides one.
+     */
+    request?: (opts: RequestLike) => Promise<unknown>;
+}
+export interface Sandbox {
+    /** Run code in the confined worker. Returns the structured result. */
+    run<T = unknown>(code: string): Promise<SandboxResult<T>>;
+}
+/**
+ * Create a sandbox over a set of adapters — the generic entry point shown in §6.2.
+ *
+ * `defineAdapter` results are bound to the injected host `request` (and a per-run abort
+ * signal) via `withContext`; plain hand-built adapters are passed through untouched. Each
+ * `run()` gets its own `AbortController`, so a timeout aborts in-flight host work.
+ */
+export declare function createSandbox(config: CreateSandboxConfig): Sandbox;

package/src/sandbox/interface.d.ts

@@ -0,0 +1,8 @@
+import type { ExecutionContext, SandboxConfig, SandboxResult } from './types';
+export interface ISandbox {
+    execute<T = unknown>(code: string, context: ExecutionContext): Promise<SandboxResult<T>>;
+    getConfig(): SandboxConfig;
+    configure(config: Partial<SandboxConfig>): void;
+    dispose(): void;
+}
+export type SandboxFactory = (config?: SandboxConfig) => ISandbox;

package/src/sandbox/node-worker.d.ts

@@ -0,0 +1,10 @@
+import type { ISandbox } from './interface';
+import type { ExecutionContext, SandboxConfig, SandboxResult } from './types';
+export declare class NodeWorkerSandbox implements ISandbox {
+    private config;
+    constructor(config?: SandboxConfig);
+    getConfig(): SandboxConfig;
+    configure(config: Partial<SandboxConfig>): void;
+    execute<T = unknown>(code: string, context: ExecutionContext): Promise<SandboxResult<T>>;
+    dispose(): void;
+}