Effects and capabilities — AEL documentation

In AEL, the Agent Engineering Language, compile-time effect and capability checks will let code do only what it has been allowed to do. A permission mistake will be caught before anything runs, with a diagnostic that shows the path to the operation that caused it.

Status

Planned for AEL Beta 0.0.1. AEL is not available yet.

Package names on this page are preview naming and may change before launch.

Effects

An effect will be something an operation does besides computing a value. The check will track these kinds:

Effect	The operation
Memory allocation	Takes memory from a heap.
Blocking	Waits without letting other work run.
Network	Opens or uses a network connection.
Remote call	Calls a service on another machine.
Model call	Sends a request to a model.
Storage	Reads or writes files or other stored data.
Clock	Reads the time.
Device access	Uses a peripheral of the board or machine.

Effects will follow every call. A function will have the effects of everything it calls, however deep: a helper function, an imported function, a package export, a hook, an output check or a tool will not be able to hide one. If a call's effects are not known, the check will treat them as unknown, never as none.

Where effects are restricted

Some kinds of code will be allowed only some effects, and the check will refuse the rest:

Code	Restriction
Configuration	No effects while it is read: no files, network, models or storage.
Edge mappings	Deterministic: no model calls, tools, network or storage. That work belongs in a node.
Hooks	Only the effects their target allows.
Real-time control paths	No model calls, no unbounded memory allocation and no blocking operations, however indirectly.
The smallest boards	No heap at all.

When the check refuses an effect, its diagnostic will show the chain of calls from your code to the operation that has the effect, so you can see where it came in.

A real-time path that passes the check will be restricted to operations that suit real-time work. The check will not by itself prove that the path meets its deadline.

Capabilities

A capability will be the permission to use something specific: a device, a network listener, a tool or a model binding. In AEL it will be a typed value that code cannot forge, build from a number or a string, or create out of nothing.

Granted by composition. The code that puts your program together, main and the configuration of your agents, will hand capabilities out.
Passed explicitly. A component will receive a capability only when it is passed one, and pass it on only by an explicit transfer.
Never widened. Child work will receive at most the permissions of the work that started it.
Checked for extensions too. Hooks, output checks and tools will obey the same capability checks as the rest of your code.

A capability will say what code may use. Who may start a run will be a separate question, checked where each request enters your program; see Services and APIs.

Prompts will never grant permissions

A system prompt, a model's output or any other text will not be able to grant a capability, remove an effect restriction or raise a limit. A rule written in a prompt, such as a speed limit for a motor, belongs in your code as well, as a typed check at the tool that moves the motor.

Packages will ask; your manifest will record it

Each package in pack.ael will list the capabilities it asks for, such as "net.listen" for a package that accepts network connections. The list will be a request, never a grant: the package will still receive only what your code passes to it.

Preview syntax — may change before launch

{ name = "server/http"; version = "^1.2.0"; kind = "runtime";
  source = { kind = "registry"; };
  features = []; targets = []; capabilities = ["net.listen"];
  publisher = "openeng"; }

Manifest reference describes the field.

Syntax

How you will declare the effects of your own functions, and the exact names of the effects, will be confirmed when the syntax is final.