Skip to main content
The Reference Sidecar keeps large strings outside the sandbox. The script holds a short reference token in place of the data and can pass that token on to another tool; the data itself is put back when a tool call leaves the sandbox. It is for scripts that move large data from one tool to another (a document, an image, a file), not for scripts that need to read that data.

How It Works

  1. Storing: A string of at least extractionThreshold bytes is stored in the sidecar and replaced by a reference token. This happens in two places: for a string literal in the script’s source, and for a tool result that is a string as a whole.
  2. The script holds a token: The token is an ordinary short string. Nothing is resolved for the script, lazily or otherwise: token.length is the length of the token, and the script has no way to read the stored data.
  3. Resolving at the tool boundary: When the script passes a token in the arguments of a tool call, at any depth, the enclave replaces it with the stored data before it calls your toolHandler.
  4. Cleanup: The sidecar belongs to one execution and is disposed when run() returns.
Only a result that is a string as a whole is stored. A tool that returns an object or an array is returned to the script as it is, with every string in it, whatever their size. To keep a large value out of the sandbox, return it as a string of its own.

Basic Configuration

Configuration Options

The defaults follow the enclave’s securityLevel:

Reference Token Format

A reference token is the text __REF_, a UUID and __:
For example: __REF_3f2b8c1e-9a4d-4e7b-8c21-5d6f7a8b9c0d__ A token means something only in the execution that produced it: the sidecar is per execution. A tool call whose arguments hold a string of this form that names no stored value fails.

Concatenation

What happens when a script concatenates a token with something else (+, += or a template literal) depends on allowComposites:
  • false (the default at STRICT and SECURE): the concatenation throws inside the script. A token can only be passed on as it is.
  • true (the default at STANDARD and PERMISSIVE): the concatenation yields a composite handle instead of a string. When the handle is passed to a tool, the enclave resolves its parts and joins them, so the tool receives the concatenated text.

Resolution Limits

Two limits bound what resolving references may build in the host:
  • maxResolvedSize applies to one tool call: the size its arguments have once every reference in them is resolved.
  • maxTotalResolvedSize applies to one execution: everything it resolves for all of its tool calls. A stored value counts once, the first time it is resolved; a concatenation of references counts every time it is built. The default is twice maxTotalSize.
A tool call whose arguments would go over either limit is refused before anything is resolved (REFERENCE_RESOLUTION_LIMIT), and the tool handler is not called. The call fails inside the script like any failing tool call.

Use Cases

Passing Large Data Between Tools

Large Literals in a Script

A string literal in the script that is at least extractionThreshold bytes long (also a template literal without substitutions) is stored before the script runs, and the script works with a token in its place. The pre-scanner’s limits on a script and on its string literals apply first: with the default agentscript preset a string literal is at most 10 KB, all string literals together at most 100 KB, and a line at most 2,000 characters, so a host that embeds larger literals raises those limits with the preScan option (preScan: { config: { maxInputSize, maxLineLength, maxStringLength, maxTotalStringContent } }, or preScan: { preset: 'standard' }). A line is at most 100,000 characters under any configuration, so a literal longer than that has to be a template literal over several lines. A literal that cannot be stored within maxReferenceSize, maxTotalSize and maxReferenceCount fails the run with ENCLAVE_ERROR.

Memory Management

  1. Bounded storage - maxTotalSize, maxReferenceSize and maxReferenceCount bound what one execution can store
  2. Bounded resolution - maxResolvedSize and maxTotalResolvedSize bound what is built for tool calls
  3. Automatic cleanup - References are cleared when the execution ends
A tool result that cannot be stored because a storage limit is reached is not stored: the script receives the string itself, under the limits that apply to every tool result.

Errors

The sidecar has no error codes of its own in result.error.code. A concatenation that is refused and a tool call that is refused for a resolution limit throw inside the script, which may catch them; uncaught, they end the run like any error of the script (see Error Codes).

Best Practices

  1. Return large values as strings - Only a result that is a string as a whole is stored
  2. Set appropriate thresholds - Too low creates many references; too high leaves large strings in the sandbox
  3. Keep composites disabled - Unless a script has to build a value around a reference
  4. Do not expect the script to read the data - A script that needs part of a large value should ask a tool for that part