Browse the documentation

Early preview

Extending the language

You extend the Open Engineering Language with code you write in the language: a component, a connection to a system you run, or a prompt. This tutorial gives a quickstart for each, packages them for reuse, and walks through the checks an extension passes before other projects use it.

Quickstart: a component

Agents, subagents, nodes (business steps), edges (typed two-way connections), configuration, hooks and skills are first-class building blocks, each in its own named file. A hook is the usual first extension: a typed function that runs before or after other code.

# src/team_only.hook.oel
struct Request {
    caller: u64,
    team: u64,
}

hook team_only(context: &EntryContext<Request>) -> HookDecision {
    return check_team(context.parameters.team);
}

fn check_team(team: u64) -> HookDecision {
    # Your policy: allow callers of your team, deny the rest.
    if team == 7 {
        return HookDecision::Allow;
    }
    return HookDecision::Deny;
}

You attach it before a component with @team_only, and the component runs only when it allows the call. Hooks attach authorization, auditing or cleanup before or after any component, function or statement, run in ordered or parallel groups, and fail closed when authorization fails. The policy in check_team is a placeholder, as A first agent explains, and Hooks lists what each context holds.

Quickstart: a connection

You write your own connectors for services, models, knowledge sources, transports and log sinks. A connector is ordinary code that declares its types, its permissions and its limits, and runs within the same budget and checks as the node that uses it:

  1. Write the typed request and result your connector exchanges with the outside system, and the typed errors it can return.
  2. Write its operations, each with the one permission it needs and whether a failed call is safe to repeat.
  3. Give its endpoint and credentials to the deployment as configuration and a secret reference, never in source.
  4. Call it from a node, like any other typed service.

Tools and MCP and Retrieval over your documents describe the kinds of connector.

Quickstart: a prompt

You write an agent's business policy as a system prompt (inline, from a file, from the environment or from configuration), or run it on its input alone with no system prompt. A prompt kept as a file is reviewed and versioned like code:

prompts/
  summarize.md       # the policy of the summarize node
  review.md          # the policy of the review node

A node names its file in the sources of its prompt as a project_file reference such as prompts/summarize.md, a path relative to the project root. System prompts describes the four sources and their order.

Recipes: package what you wrote

You build your own libraries into shareable packages that ship compiled, without your source. Put the hook, the connector and their configuration in a project whose metadata.oel names the package, then build it:

metadata {
    schema = 1;
    name = "acme/support";
    description = "Team hook and ticket connector shared by Acme's agents";
}
oel package

You build a package with the oel package command, which produces a single package file. Every public component is an export, and a project that uses the package selects each export by name in its file header:

refer acme/support select team_only;

Every package, from OpenEng or from you, is written in the language and ships in compiled, verified form, with no bundled native code and no install scripts. Creating a package and Private packages describe the file and where you host it.

Walkthrough: check an extension before others use it

Run these in the extension's project, in this order:

oel fmt --check
oel check
oel test
oel refmap
oel package
  1. Format. oel fmt --check reports files that would change.
  2. Check. oel check checks names, limits, types, visibility, hooks, targets and packages. One command-line tool checks, formats, compiles, builds and runs your code, with diagnostics that point at your source.
  3. Test. oel test runs your tests with scripted or recorded responses, so a connector is tested without the system it connects to. Test the failures too: a denied permission, a timeout, a cancellation and malformed output.
  4. Map. oel refmap shows what references what and lists unused code and packages, so the package exports only what you meant to export.
  5. Package. oel package checks the whole project again before it writes the file.

Then use the package from a second project, the way its users do, and run oel check and oel test there.

Honest limits

  • A hook runs only when your program runs: no hook runs while you check or build, and no hook can change what the Compiler does.
  • A connector's permissions keep your own code from reaching what it should not; they are not a sandbox for a hostile program. For a sandbox, you mark an agent, node or subagent as isolated: it always runs in a sandbox in its own process, reachable only through the edges you declare, as Isolated components describes. Isolation needs the isolation facilities of Linux and runs only on the Linux target the documentation names for it: on any host without those facilities, an isolated component is refused, never run without isolation. A function in another language runs on the same machine by default or in a sandbox, which needs the isolation facilities of Linux and runs only on the Linux target the documentation names for it; see Sandbox mode and isolated components.
  • A package file holds compiled files and its exports' types, never your source, so its users check their calls against the exports, not against your code.