Embeddable, sandboxed scripting to power AI agents
npm install @rcrsr/rillEmbeddable, sandboxed scripting runtime for rill. Zero dependencies. Browser and Node.js compatible.
> Experimental. Breaking changes will occur before stabilization.
``bash`
npm install @rcrsr/rill
`typescript
import { parse, execute, createRuntimeContext } from '@rcrsr/rill';
const script =
prompt("Analyze this code for issues")
-> .contains("ERROR") ? error($) ! "Analysis complete";
const ctx = createRuntimeContext({
functions: {
prompt: {
params: [{ name: 'message', type: 'string' }],
fn: async (args) => await callYourLLM(args[0]),
},
},
});
const result = await execute(parse(script), ctx);
console.log(result.value);
`
``
Source Text → parse() → AST → execute() → Result
| Export | Purpose |
|--------|---------|
| parse(source) | Parse rill source into an AST |execute(ast, ctx)
| | Execute an AST with a runtime context |createRuntimeContext(opts)
| | Create a configured runtime context |callable(fn, isProperty?)
| | Wrap a function as a rill-callable value |prefixFunctions(prefix, fns)
| | Namespace host functions (e.g., app::) |
`typescript
const ctx = createRuntimeContext({
// Host functions available to scripts
functions: {
prompt: {
params: [{ name: 'text', type: 'string' }],
fn: async (args, ctx, location) => { / ... / },
},
},
// Variables injected into script scope
variables: {
config: { greeting: 'hello' },
},
// Callbacks
callbacks: {
onLog: (value) => console.log(value),
},
// Observability hooks
observability: {
onStepStart: (e) => { / ... / },
onStepEnd: (e) => { / ... / },
},
// Execution limits
timeout: 30000,
signal: abortController.signal,
});
`
Step through execution one statement at a time:
`typescript
import { parse, createRuntimeContext, createStepper } from '@rcrsr/rill';
const stepper = createStepper(parse(script), createRuntimeContext());
let step;
while (!(step = await stepper.next()).done) {
console.log(step.value);
}
`
| Export | Purpose |
|--------|---------|
| parseWithRecovery(source) | Parse with error recovery (for editors) |tokenize(source)
| | Tokenize source into a token stream |TOKEN_HIGHLIGHT_MAP
| | Syntax highlighting category map |getLanguageReference()
| | LLM-optimized language reference text |getDocumentationCoverage()
| | Coverage stats for doc examples |getFunctions()
| | List of built-in function metadata |VERSION
| / VERSION_INFO | Runtime version string and metadata |
`typescript
import { parse, execute, createRuntimeContext, AbortError } from '@rcrsr/rill';
try {
const result = await execute(parse(script), ctx);
} catch (err) {
if (err instanceof AbortError) {
// Execution was cancelled via signal
}
// Runtime errors include source location and error code
}
`
| Export | Purpose |
|--------|---------|
| isDict(value) | Check if value is a rill dict |isTuple(value)
| | Check if value is a rill tuple |isCallable(value)
| | Check if value is any callable |isScriptCallable(value)
| | Check if value is a script-defined closure |isApplicationCallable(value)` | Check if value is a host-provided callable |
|
| Document | Description |
|----------|-------------|
| Host Integration | Embedding guide |
| Host API Reference | Complete TypeScript API |
| Language Reference | Language specification |
| Extensions | Reusable host function packages |
MIT