Reference Sidecar

The Reference Sidecar handles large data in AgentScript without embedding it in the script. This prevents memory issues and improves security when tools return large responses.

How It Works

Extraction: When a tool returns data with large strings (> extractionThreshold), those strings are stored in the sidecar and replaced with reference tokens (__ref_abc123)
Lazy Resolution: When script code accesses a reference token, it’s resolved just-in-time to the actual data
Safe Property Access: Only explicit property accesses trigger resolution, preventing data exfiltration

Basic Configuration

import { Enclave } from '@enclave-vm/core';

const enclave = new Enclave({
  toolHandler: async (name, args) => {
    if (name === 'documents:get') {
      // Returns a 2MB document - automatically stored in sidecar
      return { content: '...2MB of text...' };
    }
  },
  sidecar: {
    enabled: true,
    extractionThreshold: 1024,    // Extract strings > 1KB
    allowComposites: false,        // Block: ref + "_suffix" (security)
  },
});

const result = await enclave.run(`
  const doc = await callTool('documents:get', { id: 'doc-123' });
  // doc.content is a reference token, resolved on access
  return { wordCount: doc.content.split(' ').length };
`);

Configuration Options

Option	Type	Default	Description
`sidecar.enabled`	boolean	false	Enable the sidecar feature
`sidecar.maxTotalSize`	number	10MB	Maximum total size of all stored references
`sidecar.maxReferenceSize`	number	1MB	Maximum size of a single reference
`sidecar.extractionThreshold`	number	1024	Minimum string size to extract (bytes)
`sidecar.allowComposites`	boolean	false	Allow string concatenation with references

Reference Token Format

Reference tokens follow this pattern:

__ref_<random-id>

For example: __ref_abc123def456 Scripts cannot distinguish between reference tokens and regular strings until they access the data.

Security: Composite Blocking

When allowComposites: false (default), the sidecar blocks string concatenation with reference tokens:

// This will fail if allowComposites is false
const code = `
  const doc = await callTool('documents:get', { id: 'doc-123' });
  const modified = doc.content + '_suffix';  // Blocked!
  return modified;
`;

This prevents data exfiltration via string manipulation.

Use Cases

Large API Responses

const enclave = new Enclave({
  toolHandler: async (name, args) => {
    if (name === 'api:fetch') {
      const response = await fetch(args.url);
      return response.json(); // Could be large
    }
  },
  sidecar: {
    enabled: true,
    extractionThreshold: 10000, // 10KB threshold
  },
});

Document Processing

const enclave = new Enclave({
  toolHandler: async (name, args) => {
    if (name === 'documents:list') {
      // Returns array with potentially large content fields
      return documents.map(d => ({
        id: d.id,
        title: d.title,
        content: d.content, // Large strings extracted automatically
      }));
    }
  },
  sidecar: {
    enabled: true,
    maxTotalSize: 50 * 1024 * 1024, // 50MB total
  },
});

Multi-Step Workflows

const result = await enclave.run(`
  // Step 1: Fetch document (content stored in sidecar)
  const doc = await callTool('documents:get', { id: 'doc-123' });

  // Step 2: Extract metadata (doesn't resolve content)
  const metadata = { id: doc.id, title: doc.title };

  // Step 3: Process content only if needed
  if (metadata.title.includes('important')) {
    // Content resolved lazily here
    const words = doc.content.split(' ').length;
    return { ...metadata, words };
  }

  return metadata;
`);

Memory Management

The sidecar helps manage memory in several ways:

Bounded storage - maxTotalSize prevents unbounded growth
Per-reference limits - maxReferenceSize caps individual entries
Lazy loading - Data only loaded when accessed
Automatic cleanup - References cleared after execution

Error Handling

const result = await enclave.run(code);

if (!result.success) {
  if (result.error?.code === 'SIDECAR_SIZE_EXCEEDED') {
    console.log('Too much data stored in sidecar');
  }
  if (result.error?.code === 'SIDECAR_COMPOSITE_BLOCKED') {
    console.log('String concatenation with reference blocked');
  }
}

Monitoring Sidecar Usage

const result = await enclave.run(code);

if (result.success) {
  console.log('Sidecar stats:', {
    referencesCreated: result.stats.sidecar?.referencesCreated,
    totalBytesStored: result.stats.sidecar?.totalBytesStored,
    resolutionCount: result.stats.sidecar?.resolutionCount,
  });
}

Best Practices

Set appropriate thresholds - Too low creates many references; too high defeats the purpose
Monitor total size - Track sidecar usage to tune maxTotalSize
Keep composites disabled - Unless you specifically need string concatenation
Use with large tool responses - Most beneficial when tools return KB+ of data

Tool System - Tool integration
Configuration - All configuration options
Security Levels - Security presets

Get Started

Concepts

@enclave-vm/core

@enclave-vm/browser

@enclave-vm/ast

EnclaveJS Streaming

Guides

Examples

Troubleshooting

How It Works

Basic Configuration

Configuration Options

Reference Token Format

Security: Composite Blocking

Use Cases

Large API Responses

Document Processing

Multi-Step Workflows

Memory Management

Error Handling

Monitoring Sidecar Usage

Best Practices

​How It Works

​Basic Configuration

​Configuration Options

​Reference Token Format

​Security: Composite Blocking

​Use Cases

​Large API Responses

​Document Processing

​Multi-Step Workflows

​Memory Management

​Error Handling

​Monitoring Sidecar Usage

​Best Practices

​Related

How It Works

Basic Configuration

Configuration Options

Reference Token Format

Security: Composite Blocking

Use Cases

Large API Responses

Document Processing

Multi-Step Workflows

Memory Management

Error Handling

Monitoring Sidecar Usage

Best Practices

Related