Saved Functions
Relevant source files
The following files were used as context for generating this wiki page:
- crates/coral-functions/src/types.rs
- crates/coral-v8/src/js/compiler/saved_function_linking.js
- crates/coral-v8/src/js/compiler/authored_source_policy.js
- crates/coral-grpc/proto/coral/management/v1/saved_function.proto
- crates/coral-run/src/admission.rs
- crates/coral-v8/src/js/compiler/typescript_environment.js
- apps/reef/app/views/functions/functions-page.tsx
- README.md
Saved Functions are reusable, sandboxed TypeScript programs that agents save to build on successful workflows. They provide a mechanism for agents to persist complex logic as typed operations that appear in Universal Search alongside standard provider operations. When an agent saves a function, it identifies the code by a dotted JavaScript path relative to coral.functions.
These functions run in an isolated V8 sandbox without direct network access or standard imports. Coral manages credentials and validates every call against workspace policies. A Saved Function consists of authored source code, a compiler-emitted declaration for type checking, and advisory diagnostics retained from the time of saving.
Sources: README.md:16-19, crates/coral-functions/src/types.rs:556-565
Core Data Model
A Saved Function is defined by its identity, ownership, and authored content. The system enforces strict size and structural bounds to ensure performance and security.
Data Structures
| Component | Type | Constraint | Description |
|---|---|---|---|
| Path | SavedFunctionPath | Max 16 segments, 256 bytes | Dotted JS path relative to coral.functions. |
| Source | SavedFunctionSource | Max 64 KiB | Exact authored TypeScript module source. |
| Declaration | SavedFunctionDeclaration | Max 256 KiB | Emitted type definitions for static analysis. |
| Description | SavedFunctionDescription | Max 4 KiB | Human-readable explanation of the function. |
| Diagnostics | Vec<SavedFunctionDiagnostic> | Max 100 entries | Advisory compiler messages (errors/warnings). |
Sources: crates/coral-functions/src/types.rs:11-20, crates/coral-functions/src/types.rs:78-83
Validation Logic
Paths must contain only safe JavaScript identifier segments. Coral rejects reserved keywords and invalid characters to prevent namespace collisions or injection.
Static Analysis and Security Policy
Coral performs static analysis on authored source code to enforce a strict security perimeter. The authored_source_policy.js module identifies forbidden capabilities and analyzes dependencies.
Forbidden Capabilities
Saved Functions cannot use ambient globals or browser/Node.js APIs that provide side effects. Forbidden elements include:
- Dynamic Code Execution:
eval(),new Function(). - Networking:
fetch(),XMLHttpRequest. - Environment Access:
process.env,globalThisaccess to restricted properties. - Imports: Authored
importdeclarations orrequire()calls.
Sources: crates/coral-v8/src/js/compiler/authored_source_policy.js:145-164
Dependency Discovery
The compiler walks the Abstract Syntax Tree (AST) to find references to other Saved Functions. It specifically looks for property access starting with coral.functions.
Linking and Runtime Execution
Linking combines multiple Saved Functions and a main program into a single executable closure. This process occurs during "Program Admission."
The Linking Process
- Blanking: The linker replaces
exportsyntax with spaces in the authored source. This maintains line and column numbers so diagnostics remain accurate to the original source. - Naming: The linker assigns a private default name to each function module (e.g.,
__coralSavedFunctionDefaultExport_1). - Namespace Construction: It creates a frozen object hierarchy under
coral.functionsthat maps to the assigned private names. - Closure Resolution: During admission, Coral performs a Breadth-First Search (BFS) to resolve the full closure of all dependent functions.
Sources: crates/coral-v8/src/js/compiler/saved_function_linking.js:1-12, crates/coral-v8/src/js/compiler/saved_function_linking.js:145-155, crates/coral-run/src/admission.rs:218-245
Runtime Wrapper Structure
Linked programs are wrapped in a private asynchronous IIFE (Immediately Invoked Function Expression).
Management and UI
The SavedFunctionService gRPC API provides methods for users to manage their functions within a workspace.
API Operations
- ListSavedFunctions: Returns source-free summaries in path order. Results are paged (max 100 per page).
- GetSavedFunction: Returns the full definition including source, declaration, and diagnostics.
- DeleteSavedFunction: Removes the function and records a lifecycle event. Deletion causes admission failure for any program attempting to call the deleted path.
Sources: crates/coral-grpc/proto/coral/management/v1/saved_function.proto:13-20, crates/coral-grpc/src/grpc/saved_functions.rs:88-105
UI Cataloging
The Reef UI organizes Saved Functions into namespaces based on their path segments. For example, finance.monthlyTotals and finance.overdueInvoices are grouped under the finance namespace.
- Top-level functions: Functions with no dots in their path appear outside groups.
- Namespaced functions: Functions are split at the first dot to determine their group.
- Policy Preview: Displays the execution policy (currently "Always allow" is the default).
Sources: apps/reef/app/views/functions/functions-page.tsx:43-58, apps/reef/app/views/functions/functions-page.tsx:112-120
Implementation Constraints
Coral enforces several hard limits to maintain system stability during compilation and execution.
| Constraint | Value | Source |
|---|---|---|
| Max Combined Source Size | 2 MiB | crates/coral-run/src/admission.rs |
| Max Linked Functions | 100 | crates/coral-run/src/admission.rs |
| Compilation Timeout | 2 seconds | crates/coral-v8/src/compiler.rs |
| Max Diagnostic Msg | 4 KiB | crates/coral-functions/src/types.rs |
Sources: crates/coral-run/src/admission.rs:322-330, crates/coral-v8/src/compiler.rs:28, crates/coral-functions/src/types.rs:20
Saved Functions enable agents to transition from discovering operations to defining their own reusable capabilities. By providing a typed, sandboxed environment with strict static analysis, Coral ensures these extensions remain secure and maintainable within a multi-user workspace.