How It Works
- Storing: A string of at least
extractionThresholdbytes 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. - The script holds a token: The token is an ordinary short string. Nothing is resolved for the script, lazily or otherwise:
token.lengthis the length of the token, and the script has no way to read the stored data. - 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. - Cleanup: The sidecar belongs to one execution and is disposed when
run()returns.
Basic Configuration
Configuration Options
The defaults follow the enclave’s
securityLevel:
Reference Token Format
A reference token is the text__REF_, a UUID and __:
__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 atSTRICTandSECURE): the concatenation throws inside the script. A token can only be passed on as it is.true(the default atSTANDARDandPERMISSIVE): 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:maxResolvedSizeapplies to one tool call: the size its arguments have once every reference in them is resolved.maxTotalResolvedSizeapplies 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 twicemaxTotalSize.
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 leastextractionThreshold 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
- Bounded storage -
maxTotalSize,maxReferenceSizeandmaxReferenceCountbound what one execution can store - Bounded resolution -
maxResolvedSizeandmaxTotalResolvedSizebound what is built for tool calls - Automatic cleanup - References are cleared when the execution ends
Errors
The sidecar has no error codes of its own inresult.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
- Return large values as strings - Only a result that is a string as a whole is stored
- Set appropriate thresholds - Too low creates many references; too high leaves large strings in the sandbox
- Keep composites disabled - Unless a script has to build a value around a reference
- 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
Related
- Tool System - Tool integration
- Configuration - All configuration options
- Security Levels - Security presets