> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentfront.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# @enclave-vm/core

> API reference for the @enclave-vm/core package

API reference for the `@enclave-vm/core` package.

## Installation

```bash theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
npm install @enclave-vm/core
```

## Enclave Class

The main class for secure code execution.

### Constructor

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
new Enclave(options?: EnclaveOptions)
```

### EnclaveOptions

| Property        | Type                      | Default      | Description                      |
| --------------- | ------------------------- | ------------ | -------------------------------- |
| `securityLevel` | `SecurityLevel`           | `'STANDARD'` | Security preset                  |
| `timeout`       | `number`                  | `30000`      | Execution timeout in ms          |
| `maxToolCalls`  | `number`                  | `100`        | Maximum tool calls per execution |
| `maxIterations` | `number`                  | `10000`      | Maximum loop iterations          |
| `memoryLimit`   | `number`                  | `67108864`   | Memory limit in bytes (64MB)     |
| `toolHandler`   | `ToolHandler`             | `undefined`  | Tool execution function          |
| `globals`       | `Record<string, unknown>` | `{}`         | Custom globals                   |
| `scoringGate`   | `ScoringGateOptions`      | `undefined`  | AI scoring configuration         |
| `adapter`       | `EnclaveAdapter`          | `undefined`  | Execution adapter                |
| `verboseErrors` | `boolean`                 | `false`      | Include detailed error info      |

### Methods

#### run(code, options?)

Execute code in the sandbox.

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
async run(code: string, options?: RunOptions): Promise<ExecutionResult>
```

**Parameters:**

* `code` - JavaScript code to execute
* `options` - Optional execution options

**Returns:** `ExecutionResult`

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
interface RunOptions {
  timeout?: number;
  context?: Record<string, unknown>;
  maxToolCalls?: number;
}

interface ExecutionResult {
  success: boolean;
  value?: unknown;
  error?: ExecutionError;
  stdout?: string;
  stats?: ExecutionStats;
}
```

**Example:**

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
const result = await enclave.run(`
  const x = 1 + 2;
  return x;
`);
console.log(result.value); // 3
```

#### validate(code)

Validate code without executing.

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
async validate(code: string): Promise<ValidationResult>
```

**Returns:** `ValidationResult`

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
interface ValidationResult {
  valid: boolean;
  issues: ValidationIssue[];
}

interface ValidationIssue {
  rule: string;
  message: string;
  severity: 'error' | 'warning';
  location?: {
    line: number;
    column: number;
  };
}
```

**Example:**

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
const validation = await enclave.validate(`
  eval('dangerous');
`);
// validation.valid === false
// validation.issues[0].message === "Identifier 'eval' is not allowed"
```

#### dispose()

Clean up resources.

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
dispose(): void
```

**Example:**

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
const enclave = new Enclave();
try {
  await enclave.run(code);
} finally {
  enclave.dispose();
}
```

## Types

### SecurityLevel

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
type SecurityLevel = 'STRICT' | 'SECURE' | 'STANDARD' | 'PERMISSIVE';
```

| Level        | Description                          |
| ------------ | ------------------------------------ |
| `STRICT`     | Maximum security for untrusted code  |
| `SECURE`     | High security for semi-trusted code  |
| `STANDARD`   | Balanced security for internal tools |
| `PERMISSIVE` | Minimal restrictions (testing only)  |

### ToolHandler

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
type ToolHandler = (
  name: string,
  args: Record<string, unknown>,
  context?: Record<string, unknown>
) => Promise<unknown>;
```

**Example:**

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
const toolHandler: ToolHandler = async (name, args, context) => {
  switch (name) {
    case 'users:list':
      return db.users.findAll({ limit: args.limit });
    default:
      throw new Error(`Unknown tool: ${name}`);
  }
};
```

### ExecutionError

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
interface ExecutionError {
  code: ErrorCode;
  name: string;
  message: string;
  stack?: string;
  data?: Record<string, unknown>;
}

type ErrorCode =
  | 'VALIDATION_ERROR'
  | 'TIMEOUT'
  | 'MAX_TOOL_CALLS'
  | 'MAX_ITERATIONS'
  | 'TOOL_ERROR'
  | 'MEMORY_LIMIT_EXCEEDED'
  | 'SCORING_BLOCKED'
  | 'RUNTIME_ERROR';
```

### ExecutionStats

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
interface ExecutionStats {
  duration: number;
  toolCallCount: number;
  iterationCount: number;
  memoryUsage?: number;
}
```

### ScoringGateOptions

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
interface ScoringGateOptions {
  scorer: 'rule-based' | 'custom';
  blockThreshold: number;
  warnThreshold?: number;
  onScore?: (result: ScoringResult) => void;
  customScorer?: (code: string) => Promise<ScoringResult>;
}

interface ScoringResult {
  score: number;
  signals: string[];
}
```

## Factory Functions

### createWorkerPoolAdapter(options)

Create a worker pool adapter for OS-level isolation.

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
function createWorkerPoolAdapter(options: WorkerPoolOptions): EnclaveAdapter
```

**Options:**

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
interface WorkerPoolOptions {
  poolSize: number;
  maxWorkerMemory?: number;
  maxExecutionsPerWorker?: number;
  idleTimeout?: number;
}
```

**Example:**

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
import { Enclave, createWorkerPoolAdapter } from '@enclave-vm/core';

const enclave = new Enclave({
  adapter: createWorkerPoolAdapter({
    poolSize: 4,
    maxWorkerMemory: 128 * 1024 * 1024,
  }),
});
```

### createDoubleVmAdapter(options)

Create a double-VM adapter for nested isolation.

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
function createDoubleVmAdapter(options?: DoubleVmOptions): EnclaveAdapter
```

**Options:**

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
interface DoubleVmOptions {
  outerTimeout?: number;
  innerTimeout?: number;
}
```

## RuleBasedScorer Class

Semantic pattern detection scorer.

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
import { RuleBasedScorer } from '@enclave-vm/core';

const scorer = new RuleBasedScorer();
const result = scorer.score(code);

console.log(result.score);   // 0-100
console.log(result.signals); // ['list-send-pattern', 'bulk-operation']
```

### Methods

#### score(code)

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
score(code: string): ScoringResult
```

## Reference Sidecar

Handle large tool responses.

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
import { Enclave } from '@enclave-vm/core';

const enclave = new Enclave({
  sidecar: {
    enabled: true,
    threshold: 1024 * 1024, // 1MB
  },
});
```

### SidecarOptions

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
interface SidecarOptions {
  enabled: boolean;
  threshold?: number; // Size threshold for reference creation
  storage?: 'memory' | 'redis';
  ttl?: number; // Time-to-live in ms
}
```

## Complete Example

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
import { Enclave, createWorkerPoolAdapter } from '@enclave-vm/core';

// Create enclave with full configuration
const enclave = new Enclave({
  // Security
  securityLevel: 'STRICT',

  // Limits
  timeout: 30000,
  maxToolCalls: 50,
  maxIterations: 10000,
  memoryLimit: 64 * 1024 * 1024,

  // Custom globals
  globals: {
    config: { debug: true },
  },

  // Tool handling
  toolHandler: async (name, args) => {
    console.log(`Tool: ${name}`, args);
    return { success: true };
  },

  // AI Scoring
  scoringGate: {
    scorer: 'rule-based',
    blockThreshold: 70,
    warnThreshold: 40,
    onScore: (result) => {
      console.log('Score:', result.score);
    },
  },

  // Worker pool isolation
  adapter: createWorkerPoolAdapter({
    poolSize: 4,
  }),
});

// Execute code
const result = await enclave.run(`
  console.log('Hello from Enclave');
  const data = await callTool('fetch', { url: '/api/data' });
  return data;
`);

console.log(result);

// Clean up
enclave.dispose();
```

## Related

* [Overview](/enclave/core-libraries/enclave-vm/overview) - Feature overview
* [Configuration](/enclave/core-libraries/enclave-vm/configuration) - All options
* [Security Levels](/enclave/core-libraries/enclave-vm/security-levels) - Security details