Browse the documentation

Early preview

Isolated components

In the Open Engineering Language, you mark an agent, node or subagent as isolated: it always runs in a sandbox in its own process, outside the shared communication layer, reachable only through the edges you declare and holding only the resources it declares itself. Isolation needs the isolation facilities of Linux and runs only on the Linux target the documentation names for it. Honest limits says what happens on any other host.

The isolated modifier

isolated comes before the keyword of the declaration:

# src/billing.agent.oel
isolated agent billing(invoice: Str<256>) -> Str<256> {
    config {
        id: "billing"; version: "1.0.0";
        ports: [
            { id: "input"; direction: "input"; schema_type: "String<256>";
              modalities: ["text"]; min_count: 1; max_count: 1;
              max_bytes: 256; join: "all"; },
            { id: "result"; direction: "output"; schema_type: "String<256>";
              modalities: ["text"]; min_count: 1; max_count: 1;
              max_bytes: 256; join: "all"; }
        ];
        limits: {
            ram_bytes: 33554432; cpu_millicores: 1000; cpu_millis: 8000;
            duration_ms: 120000; input_tokens: 0; output_tokens: 0;
            model_calls: 0; tool_calls: 0; steps: 10000; concurrency: 2;
            max_children: 1; max_depth: 2; queue_items: 1; queued_bytes: 65536;
            stream_bytes_per_second: 0; storage_bytes: 0; connections: 0;
            cost_microunits: 0;
        };
        authority: []; capabilities: []; profile: "host"; state_domain: "request";
        nodes: [{ id: "totaler"; source: "src/nodes/total_invoice.node.oel"; }];
        agents: []; edges: []; starts: ["totaler"];
        inputs: [{ port: "input"; to: { instance: "totaler"; port: "input"; }; }];
        dispatch: "sequential";
        completion: { kind: "all"; result: { instance: "totaler"; port: "result"; }; };
    }
    return invoice;
}

Its node, in its smallest form:

# src/nodes/total_invoice.node.oel
isolated node total_invoice(input: Str<256>) -> Str<256> {
    config {
        id: "total_invoice"; version: "1.0.0"; policy: { kind: "deterministic"; entry: "total_invoice"; };
        ports: [{ id: "input"; direction: "input"; schema_type: "String<256>"; modalities: ["text"]; min_count: 1; max_count: 1; max_bytes: 256; join: "all"; },
                { id: "result"; direction: "output"; schema_type: "String<256>"; modalities: ["text"]; min_count: 1; max_count: 1; max_bytes: 256; join: "all"; }];
        limits: { ram_bytes: 1048576; cpu_millicores: 1000; cpu_millis: 1000; duration_ms: 5000; input_tokens: 0; output_tokens: 0;
                  model_calls: 0; tool_calls: 0; steps: 16; concurrency: 1; max_children: 0; max_depth: 0; queue_items: 1; queued_bytes: 65536;
                  stream_bytes_per_second: 0; storage_bytes: 0; connections: 0; cost_microunits: 0; };
        authority: []; profile: "host"; state_domain: "request"; capabilities: []; tools: []; assets: [];
        prompt: null; prompt_variables: null; binding: null; binding_capability_revision: null;
    }
    return input;
}
# src/nodes/scrub.node.oel
isolated node scrub(input: Str<4000>) -> Str<4000> {
    config {
        id: "scrub"; version: "1.0.0"; policy: { kind: "deterministic"; entry: "scrub"; };
        ports: [{ id: "input"; direction: "input"; schema_type: "String<4000>"; modalities: ["text"]; min_count: 1; max_count: 1; max_bytes: 4000; join: "all"; },
                { id: "result"; direction: "output"; schema_type: "String<4000>"; modalities: ["text"]; min_count: 1; max_count: 1; max_bytes: 4000; join: "all"; }];
        limits: { ram_bytes: 1048576; cpu_millicores: 1000; cpu_millis: 1000; duration_ms: 5000; input_tokens: 0; output_tokens: 0;
                  model_calls: 0; tool_calls: 0; steps: 16; concurrency: 1; max_children: 0; max_depth: 0; queue_items: 1; queued_bytes: 65536;
                  stream_bytes_per_second: 0; storage_bytes: 0; connections: 0; cost_microunits: 0; };
        authority: []; profile: "host"; state_domain: "request"; capabilities: []; tools: []; assets: [];
        prompt: null; prompt_variables: null; binding: null; binding_capability_revision: null;
    }
    return remove_secrets(input);
}

fn remove_secrets(record: Str<4000>) -> Str<4000> {
    # Your rules for what may leave the record. This placeholder passes it unchanged.
    return record;
}
# src/issue_reader.subagent.oel
isolated subagent issue_reader(issue: u64) -> u64 {
    config {
        id: "issue_reader"; version: "1.0.0";
        ports: [
            { id: "input"; direction: "input"; schema_type: "u64";
              modalities: ["json"]; min_count: 1; max_count: 1;
              max_bytes: 32; join: "all"; },
            { id: "result"; direction: "output"; schema_type: "u64";
              modalities: ["json"]; min_count: 1; max_count: 1;
              max_bytes: 32; join: "all"; }
        ];
        limits: {
            ram_bytes: 33554432; cpu_millicores: 1000; cpu_millis: 8000;
            duration_ms: 120000; input_tokens: 0; output_tokens: 0;
            model_calls: 0; tool_calls: 0; steps: 10000; concurrency: 2;
            max_children: 1; max_depth: 2; queue_items: 1; queued_bytes: 65536;
            stream_bytes_per_second: 0; storage_bytes: 0; connections: 0;
            cost_microunits: 0;
        };
        authority: []; capabilities: []; profile: "host"; state_domain: "request";
        nodes: [{ id: "parser"; source: "src/nodes/parse_issue.node.oel"; }];
        agents: []; edges: []; starts: ["parser"];
        inputs: [{ port: "input"; to: { instance: "parser"; port: "input"; }; }];
        dispatch: "sequential";
        completion: { kind: "all"; result: { instance: "parser"; port: "result"; }; };
    }
    return issue;
}

Its node, in its smallest form:

# src/nodes/parse_issue.node.oel
isolated node parse_issue(input: u64) -> u64 {
    config {
        id: "parse_issue"; version: "1.0.0"; policy: { kind: "deterministic"; entry: "parse_issue"; };
        ports: [{ id: "input"; direction: "input"; schema_type: "u64"; modalities: ["json"]; min_count: 1; max_count: 1; max_bytes: 32; join: "all"; },
                { id: "result"; direction: "output"; schema_type: "u64"; modalities: ["json"]; min_count: 1; max_count: 1; max_bytes: 32; join: "all"; }];
        limits: { ram_bytes: 1048576; cpu_millicores: 1000; cpu_millis: 1000; duration_ms: 5000; input_tokens: 0; output_tokens: 0;
                  model_calls: 0; tool_calls: 0; steps: 16; concurrency: 1; max_children: 0; max_depth: 0; queue_items: 1; queued_bytes: 65536;
                  stream_bytes_per_second: 0; storage_bytes: 0; connections: 0; cost_microunits: 0; };
        authority: []; profile: "host"; state_domain: "request"; capabilities: []; tools: []; assets: [];
        prompt: null; prompt_variables: null; binding: null; binding_capability_revision: null;
    }
    return input;
}
  • The modifier is part of the declaration. It is neither a hook attribute nor a configuration field, so no configuration can set it or remove it.
  • The file keeps its name: billing.agent.oel, scrub.node.oel, issue_reader.subagent.oel.
  • Only an agent, a node or a subagent takes the modifier. The check refuses isolated before main, a global or reusable function, a hook, a configuration, an edge or any other role.
  • The body of remove_secrets is a placeholder, as A first agent explains.

What isolation gives

AspectAn isolated component
Where it runsAlways in a sandbox, in its own process.
Who reaches itOnly the edges declared to it. It is outside the shared communication layer, so nothing else can call it or send it a value.
What it holdsOnly the bindings it declares itself: nothing inherited from the agent around it and nothing granted to it through a spawn or an edge.
What ends itA cancellation or its deadline, either of which ends its process.

Reached only through its edges

When an agent reaches an isolated node through one edge, only that agent, through that edge, communicates with the node. No other agent, node or subagent reaches it, and the node reaches nothing except through its own declared edges. A frame that arrives on an edge it did not declare ends its process, and no value reaches it before its sandbox has reported itself applied. An edge to an isolated component carries values only: never a storage handle, a file or a descriptor.

# src/intake.agent.oel
agent intake(input: Str<4000>) -> Str<4000> {
    config {
        id: "intake"; version: "1.0.0";
        ports: [
            { id: "input"; direction: "input"; schema_type: "String<4000>";
              modalities: ["text"]; min_count: 1; max_count: 1;
              max_bytes: 4000; join: "all"; },
            { id: "result"; direction: "output"; schema_type: "String<4000>";
              modalities: ["text"]; min_count: 1; max_count: 1;
              max_bytes: 4000; join: "all"; }
        ];
        limits: {
            ram_bytes: 33554432; cpu_millicores: 1000; cpu_millis: 8000;
            duration_ms: 120000; input_tokens: 0; output_tokens: 0;
            model_calls: 0; tool_calls: 0; steps: 10000; concurrency: 2;
            max_children: 3; max_depth: 2; queue_items: 1; queued_bytes: 65536;
            stream_bytes_per_second: 0; storage_bytes: 0; connections: 0;
            cost_microunits: 0;
        };
        authority: []; capabilities: []; profile: "host"; state_domain: "request";
        nodes: [{ id: "reader"; source: "src/nodes/read_request.node.oel"; }, { id: "scrubber"; source: "src/nodes/scrub.node.oel"; }, { id: "answerer"; source: "src/nodes/answer.node.oel"; }];
        agents: []; edges: ["src/edges/read_to_scrub.edge.oel", "src/edges/scrub_to_answer.edge.oel"]; starts: ["reader"];
        inputs: [{ port: "input"; to: { instance: "reader"; port: "input"; }; }];
        dispatch: "sequential";
        completion: { kind: "all"; result: { instance: "answerer"; port: "result"; }; };
    }
}

The agent's other nodes and edges, in their smallest form:

# src/nodes/read_request.node.oel
node read_request(input: Str<4000>) -> Str<4000> {
    config {
        id: "read_request"; version: "1.0.0"; policy: { kind: "deterministic"; entry: "read_request"; };
        ports: [{ id: "input"; direction: "input"; schema_type: "String<4000>"; modalities: ["text"]; min_count: 1; max_count: 1; max_bytes: 4000; join: "all"; },
                { id: "result"; direction: "output"; schema_type: "String<4000>"; modalities: ["text"]; min_count: 1; max_count: 1; max_bytes: 4000; join: "all"; }];
        limits: { ram_bytes: 1048576; cpu_millicores: 1000; cpu_millis: 1000; duration_ms: 5000; input_tokens: 0; output_tokens: 0;
                  model_calls: 0; tool_calls: 0; steps: 16; concurrency: 1; max_children: 0; max_depth: 0; queue_items: 1; queued_bytes: 65536;
                  stream_bytes_per_second: 0; storage_bytes: 0; connections: 0; cost_microunits: 0; };
        authority: []; profile: "host"; state_domain: "request"; capabilities: []; tools: []; assets: [];
        prompt: null; prompt_variables: null; binding: null; binding_capability_revision: null;
    }
    return input;
}
# src/nodes/answer.node.oel
node answer(input: Str<4000>) -> Str<4000> {
    config {
        id: "answer"; version: "1.0.0"; policy: { kind: "deterministic"; entry: "answer"; };
        ports: [{ id: "input"; direction: "input"; schema_type: "String<4000>"; modalities: ["text"]; min_count: 1; max_count: 1; max_bytes: 4000; join: "all"; },
                { id: "result"; direction: "output"; schema_type: "String<4000>"; modalities: ["text"]; min_count: 1; max_count: 1; max_bytes: 4000; join: "all"; }];
        limits: { ram_bytes: 1048576; cpu_millicores: 1000; cpu_millis: 1000; duration_ms: 5000; input_tokens: 0; output_tokens: 0;
                  model_calls: 0; tool_calls: 0; steps: 16; concurrency: 1; max_children: 0; max_depth: 0; queue_items: 1; queued_bytes: 65536;
                  stream_bytes_per_second: 0; storage_bytes: 0; connections: 0; cost_microunits: 0; };
        authority: []; profile: "host"; state_domain: "request"; capabilities: []; tools: []; assets: [];
        prompt: null; prompt_variables: null; binding: null; binding_capability_revision: null;
    }
    return input;
}
# src/edges/read_to_scrub.edge.oel
edge read_to_scrub(input: Str<4000>) -> Str<4000> {
    config {
        id: "read_to_scrub";
        from: { instance: "reader"; port: "result"; };
        to: { instance: "scrubber"; port: "input"; };
        mode: "request"; deadline_ms: 5000;
    }
    return input;
}
# src/edges/scrub_to_answer.edge.oel
edge scrub_to_answer(input: Str<4000>) -> Str<4000> {
    config {
        id: "scrub_to_answer";
        from: { instance: "scrubber"; port: "result"; };
        to: { instance: "answerer"; port: "input"; };
        mode: "request"; deadline_ms: 5000;
    }
    return input;
}

Here scrub is the isolated node above: read_to_scrub carries a record to it, scrub_to_answer carries its result on, and nothing else in the program reaches it. Every edge is a typed, two-way channel: the Compiler generates the communication between nodes, agents and subagents from your edge declarations, with no client or server code for you to write. The edges of an isolated component are generated in the same way; see Communication between agents.

What the check refuses

The check refuses every one of these when you check your code, with a diagnostic that points at your source:

  • Ambient tools, files or network. An isolated component calls no tool, opens no network connection and reaches no file outside its own private directory.
  • A model or tool call of its own. It makes no model or tool call itself: it reaches one through a declared edge to a node that is not isolated.
  • A function in another language on the same machine. A function in another language runs inside an isolated component only in sandbox mode; see Sandbox mode and isolated components.
  • A subagent that is not isolated. Inside an isolated component, spawn starts only isolated subagents; see Isolated subagents.
  • A binding from outside. A binding inherited from the agent around it, or passed in through a spawn or an edge, is refused.
  • A hook with an ambient effect, or a hook inside the body. A hook attaches to an isolated component only at its entry and its exit, runs inside the same boundary and holds no ambient effect; a hook statement inside its body is refused.
  • A placement of its own. An isolated component is always reached between processes: the check refuses an edge to it that you place in the same process or over the network, and the deployment places every one of its edges between processes.

Its own bindings

An agent, subagent or node declares the memory, skills, knowledge, storage and database it uses, each bound to a package you select, and the check refuses any use it did not declare. An isolated component holds exactly the bindings it declares in its own declaration, and no other. A binding that needs a network connection or a file outside the private directory is served by the agent around it: the isolated component sends its typed calls over a dedicated edge and the parent makes them, so the component never holds the connection. Bindings describes the record.

Cancellation and deadlines

  • Canceling an isolated component, or reaching its deadline, ends its process and removes its private directory.
  • What it spends counts against the budget of the agent around it, as for any child; see Budgets, retries and validation.
  • An effect outside the program whose outcome is not known stays unknown, for your code to reconcile.

Permissions are not a sandbox

Effects and capabilities keep your own code from doing what it has not been allowed to do. They are not a sandbox: when a component must run in one, mark it isolated. Code in another language has a sandbox mode of its own, which Sandbox mode and isolated components describes.

Honest limits

  • Isolation needs the isolation facilities of Linux and runs only on the Linux target the documentation names for it: on macOS, on Windows, on microcontroller boards, on other Linux targets and on any host without those facilities, an isolated component is refused, never run without isolation. Supported targets gives the exact target.
  • An isolated component reaches models, tools and the network only through its edges, so a component that needs them directly is not isolated.