Skip to content
AggregaAggrega
Select language: English

Extensibility

Ecosystem Extensibility & Compiler Guardrails

1. The Universal WebAssembly (Wasm) Interface

To ensure architectural symmetry across the ecosystem, Aggrega utilizes a standardized execution contract that applies uniformly to every Wasm socket in the compiler pipeline.

The YAML interface for invoking any plugin relies on two explicitly chosen keywords: function and with.

  • function: Aggrega embeds a Wasm runtime (the Extism toolkit on top of the Wazero engine), executing Wasm directly in memory, so no operating-system process is started. function names the export the Go host invokes: an explicitly exported function of the Wasm module.
  • with: the plugin’s own inputs, kept apart from the Developer’s values and from the parameters a Release fulfils. The keyword follows the GitHub Actions convention (with:); where a plugin declares a JSON Schema for its inputs, the host validates them against it before execution.

The Types of Wasm Plugins: This universal function and with interface supports every programmable socket in the compiler:

Plugin TypeWhere it runsPurposeExpected Output
Provider (provider)Rendering (generation)Translates the final in-memory IR into physical stringified files for a target format (Helm, Terraform, Compose).An array of stringified files.
FeatureRecipe pipeline step (pipeline-step)A Recipe’s or FeatureRecipe’s plugin pipelineSequential steps that fetch secrets or inject sidecars into base ASTs.RFC 6902 patches against the keyed document set, plus side_effects (emit a new document or file), diagnostics, and outputs a later step can read. The step input carries that keyed document set and the step’s rendered with input.
Governance (governance)Before annotation expansion, topology construction, static analysis, or the render stageServes the build-pipeline governance roles. Before annotation expansion it injects annotations onto resolved components, and at topology construction it auto-tags nodes with compliance or environmental labels (an operator opts one in to either). At static analysis or the render stage it acts as the Loud Guardrail: evaluates graph edges, paths, and labels — or the rendered artifacts — against security boundaries. The role it is attached at, not its kind, fixes what it may emit.Before annotation expansion, annotation injections. At topology construction, an array of JSONPatches targeting metadata.labels. At static analysis or the render stage, verdicts at halt, warn or info severity (a Rego policy collects them under deny, warn and audit); a halt stops the build.
Linter (linter)Out of bandOptional FinOps or hygiene checks (e.g. cloud-cost estimation from .infra) and publish-time discipline.Warning strings or fatal halts.
CLI extension (cli)Runtime (aggrega <command>)A drop-in top-level command contributed by a signed, sandboxed plugin, with zero per-command Go in the host.Streamed standard output and error, plus the guest’s exit code.
Parser (parser)On demand, wherever a foreign format is readTurns foreign source text (HCL, TOML, YAML, JSON, JSON with comments) into a canonical JSON tree.tree plus diagnostics, and optional source spans.
Importer (importer)On demand, outside any build (aggrega import, the editor, and the assistant’s import tool)Turns a foreign infrastructure or agent-definition source (Langflow, Flowise, n8n, an MCP configuration, a Compose application, a Dify application, a CrewAI project’s declared agents, a LangGraph application’s configuration, a Google ADK application’s agent configurations, an Agent Framework declarative agent) into draft Aggrega authoring files, advertising the formats it handles as import:<format> capabilities.Draft Aggregate / Component / Release entities, or references to the catalog Components it reuses, the mapping decisions behind them, diagnostics, and the scaffold files to write.

The host runtime: a capability-denying sandbox. Aggrega embeds the Wasm host as the Extism toolkit running on top of the Wazero engine; the host binary stays pure Go with no native toolchain dependency, so aggrega cross-compiles cleanly. Every socket runs behind an AOT-purity firewall: the host refuses to grant a plugin any runtime-access capability — no network, no filesystem, no wall-clock, no environment, no standard I/O — so a call that would use one fails, and a plugin importing from a host surface the host does not provide is rejected at load. A plugin that cannot reach the network or read the clock cannot break the compiler’s ahead-of-time guarantee that the same input produces the same output. Language runtimes that need a few benign startup imports run against a capability-denied configuration of those imports: the host fixes the observable wall clock, supplies real entropy, discards standard I/O, and grants no filesystem, argument, or environment access — so a plugin can reach no host capability that varies across builds. Entropy is deliberately left real rather than pinned: pinning it would stabilise a guest language runtime’s internal hash seed and map-iteration order, and so hide a plugin whose own output is not reproducible instead of letting that surface as differing output. A plugin whose result depends on entropy is an authoring-level determinism problem, and this configuration is built to reveal it rather than mask it.

Authoring against the host: the PDK. Plugin authors do not hand-write the Wasm memory ABI. Aggrega ships a Plugin Development Kit in three languages — Go, Rust, and TypeScript — thin wrappers that present each socket’s typed input and output so the author writes ordinary functions. The function / with interface above is what an Aggregate or FeatureRecipe uses to invoke a plugin; the PDK is what a plugin author builds against.

Where each socket runs. Every socket runs through the same host: the publishing linter under aggrega lint; the governance roles, the render providers and the Recipe and FeatureRecipe pipeline steps during aggrega build; parsers wherever a foreign format is read; importers under aggrega import; and CLI plugins as top-level commands. See Status of the Language for the per-socket readiness.

Which plugins are pinned, and which your environment chooses. Aggrega splits plugins by whether they change the output you ship. Output-shaping plugins — the render providers, the governance plugins attached in a transform role (label-transform, annotation-transform), and the FeatureRecipe and Recipe pipeline steps — are pinned in the release lockfile when you aggrega pull, and reproduced byte-identically at aggrega build and aggrega serve from that lockfile alone. Two kinds are not pinned, because a build reads each from the same place every time: a render provider served from inside the compiler binary, and a provider or pipeline step whose Plugin entity is authored in one of your own catalog directories. To change which output-shaping plugin applies, you re-pull; a change to your workspace configuration after a pull does not move a build’s output until the next pull. Gate plugins — policy and lint — judge a build without changing its bytes, so they are cached at pull (so a build can still run them offline; one the compiler binary carries, or one authored in your own catalog directory, is read from there instead) but not pinned: which gate runs is chosen by your environment at build time, so a dev-permissive / CI-strict split is an ordinary configuration choice rather than a re-pull, and switching gates never changes the output a passing build emits. Plugins that act only on authoring input, such as importers and CLI extensions, shape no build output and are neither pinned nor part of the build’s cached set.

2. FeatureRecipe Plugin Pipelines

FeatureRecipes bind abstract operational intents (like a security proxy attachment or a sidecar injection) to versioned WebAssembly (Wasm) plugin pipelines. Ops declares what a Feature needs at a concrete provider target; the compiler executes the declared pipeline against the flat IR graph.

This binding carries three consequences for the ecosystem:

  • Decoupling evolution. The infrastructure vocabulary grows through external Wasm plugins without requiring a core release of the Aggrega compiler. New providers, new sidecars, and new security integrations ship as independent Wasm binaries against the stable Wasm ABI.
  • Semantic versioning. FeatureRecipes reference Wasm plugins by version — exact (:1.0.0) or a caret range (:^1.0.0, the highest version compatible with it). With the caret range Ops locks down a major version while picking up its minor and patch releases whenever the lockfile is re-resolved with aggrega pull --upgrade.
  • Offloading complexity. Vendor-specific CRD generation or complex rendering (vendor-specific policy objects, provider-native routing resources) lives in pure Wasm plugins operating on the flat IR graph, rather than threading through schema declarations or template logic inside component definitions.

Pipeline chaining — separating concerns across plugins. A FeatureRecipe pipeline can chain multiple Wasm plugins sequentially, each receiving the same IR node context from the compiler. The standard pattern splits responsibility so that a single plugin does not carry both the semantic intent of a feature and the physical traffic-interception mechanism of a specific target environment.

A canonical two-plugin chain looks like this:

  • A configuration plugin that emits the semantic rules for the feature (security policy rules, audit patterns, rate-limit thresholds). It understands the feature’s intent; it does not understand the target environment’s traffic-interception fabric.
  • A routing plugin that emits the physical mesh configuration that carries those rules (gateway CRDs, sidecar injection patches, firewall rules). It understands the target environment’s fabric; it does not understand the feature’s semantic intent.

Both plugins receive the same IR node context from the compiler in sequence, so they compose cleanly without direct coupling between them. The compiler orchestrates the pipeline; the plugins carry domain knowledge.

3. Traffic Interception: The HTTPRoute Target

Aggrega’s extensibility model targets the Kubernetes Gateway API HTTPRoute standard as the cross-provider artifact for mesh-level traffic interception. The standard library emits HTTPRoute objects through the core/http-route Feature, whose helm FeatureRecipe renders one route per attached component; target environments that consume Gateway API translate HTTPRoute to their native fabrics.

4. Plugin Autonomy: Label Resolution

When Wasm plugins generate physical resources from the IR graph, SREs need to trace a running Kubernetes Pod or cloud resource back to the developer’s semantic intent in the Aggregate. Aggrega’s extensibility model places that translation entirely inside the Wasm plugin author’s control.

The compiler passes the full IR-graph labels dictionary into the Wasm sandbox without interpretation. The plugin author — Platform Ops — decides the mapping logic from there: pass all labels verbatim, filter for specific domain prefixes (*.aggrega.ai/*), or map graph labels directly to native provider tagging schemas (translating an IR label into AWS tags, Kubernetes annotations, or a cloud-specific metadata mechanism). The compiler enforces no restrictions on how the generated artifacts are tagged.

This autonomy keeps domain-specific intelligence — which labels matter for observability, which map to native tagging conventions, which are platform-internal — inside the Wasm plugin layer, where the ecosystem evolves independently of the Go compiler’s release cadence.

5. CLI Extensions: Runtime Commands

The sockets above run inside a build — the compiler dispatches them as it parses, mutates, validates, and renders an Aggregate. The CLI-extension socket is different in kind: it runs at the terminal, outside any build, when an operator types aggrega <command>. It is how the aggrega command surface itself grows without a core release.

What a CLI extension is. A CLI extension is a drop-in aggrega <command> contributed by a signed, sandboxed Wasm plugin. It takes the same guest-owned drop-in stance the rendering socket takes: the domain logic lives entirely in the guest, and the Go host contributes zero per-command code. Adding a new top-level command needs only three things — a .wasm binary, one Plugin entity declaring pluginType: cli (see Plugin), and an explicit aggrega plugin add cli. The host discovers the command from the installed plugin’s self-report; no command is compiled into the binary.

Why a runtime socket can do what a build socket cannot. Because the compile-time sockets run during a build, they stay capability-denied and deterministic: Aggrega is an ahead-of-time compiler, and the same input must always produce the same output (see Architectural Invariants). A render or policy plugin therefore cannot reach the network, read the clock, or stream to the terminal — anything that varies across runs would break that guarantee. A CLI extension runs after and outside that boundary, driven by a human at a prompt rather than by the deterministic pipeline. That is precisely why a CLI plugin may stream standard output and standard error as it runs and return a process exit code: there is no build artifact whose byte-for-byte stability those effects could threaten.

Install, run, and discover. aggrega plugin add cli <query> searches the configured registry for a matching cli plugin, verifies it against the registry’s trust policy, and installs it as a top-level command — printing the plugin’s declared capabilities first, so the operator confirms exactly what the command is allowed to do before it lands. Once installed, aggrega <command> runs it like any built-in. A CLI plugin declares its commands and their flags in its describe() self-report, and the host renders each command’s flags in aggrega help <command> exactly as it does for a built-in command, so an operator discovers an installed command’s --flags the same way. To find installable commands and catalog content, aggrega search queries the local index of configured registries — --kind plugin --plugin-type cli narrows the results to installable CLI plugins, and an unfiltered search covers catalog entities; aggrega plugin list shows what is already installed. The per-command flags and output shapes live on those reference pages.

The capability model. A CLI extension starts from a fixed baseline that every command receives with no declaration and no prompt:

Baseline capabilityGranted
Command-line arguments inAlways
Streamed standard output and standard errorAlways
Process exit code outAlways

Anything beyond the baseline is off by default. A plugin that needs more declares each additional capability explicitly, and the host grants it only after showing it at install time for the operator to confirm. A capability class added beyond the baseline — environment, filesystem or network access, interactive input — is granted behind the same declare-and-confirm gate, so a command can never silently acquire a reach the operator did not approve.

Built-ins always win. An installed plugin can never shadow a built-in command. A reserved-name guard backed by a denylist protects the built-in commands and a set of names reserved for built-ins, and a collision is refused at install rather than allowed to override core behavior. The command surface an operator relies on stays stable no matter what is installed on top of it.

6. Parser Plugins: Reading Foreign Formats

The compiler routinely needs to read text written in a format it did not author — a Terraform module in HCL, a config file in TOML, a manifest in YAML or JSON. The parser socket supplies that reading capability without teaching the compiler core any one format. A parser is a stateless plugin that turns a foreign source text into a structured JSON tree: hand it the bytes of an HCL file and it returns the same content as a JSON object the rest of the pipeline already knows how to walk. Any part of the compiler that needs to read a format it does not parse natively asks for a parsed tree and works from there.

A format is a capability, not a compiler feature. A parser advertises the formats it handles as capabilities — parse:hcl, parse:toml, and so on — and the host resolves a parser by the requested format, runs it, and hands the tree back. This is the same drop-in, capability-advertised model the render providers and CLI plugins take: the compiler core holds no built-in list of formats, so adding one is shipping a new parser plugin, never a core release. Parsers for HCL, TOML, YAML, JSON, and JSON with comments ship inside the binary as a starter set; an enterprise that needs another format ships a parser plugin that advertises it.

Format selection is declarative, never guessed. The host never inspects a file’s content to decide what it is. It picks a format through declared signals in a fixed order of preference. A render provider can declare the format of each file it emits, and the host prefers that producer-declared format outright — the provider that wrote the bytes is the authority on how to read them. For a file the producer did not tag, a fixed file-extension map is the fallback — .tf selects HCL, .toml selects TOML, .yaml selects YAML, .json selects JSON. Choosing by a declared format or a fixed extension keeps parsing deterministic and legible: the same input always routes to the same parser, and an operator can read off which parser will run without knowing the bytes inside the file. Content-sniffing would make the choice depend on the payload, and Aggrega does not do it.

A parser is purely syntactic. The output is a JSON tree plus diagnostics, and optionally the source locations each node came from. A parser carries no Aggrega meaning — it reports what the text says structurally, nothing about what it means as a Component, a Recipe, or any other entity. Turning a parsed tree into Aggrega entities is a separate concern that lives elsewhere; the parser’s single job is faithful syntax-to-JSON translation. The reading direction is one-way in the same spirit: a parser reads a format into a tree, it does not write a format back out.

A consumer: policy over Terraform HCL. A render-stage policy that needs to inspect the Terraform a build produces does not learn HCL itself. The host parses the HCL artifact through the parser socket and hands the policy plugin the JSON tree it already reads, so the policy reasons over structured data in the shape every other socket receives. New readers of foreign formats compose the same way — ask the host for the tree, then work in JSON — so the compiler’s ability to understand a format grows by adding parser plugins rather than by growing the core.

7. Importer Plugins: Drafting Authoring Files From Foreign Sources

A team rarely starts from a blank page. Its agent architecture often already exists somewhere else — a Langflow or Flowise flow, an n8n workflow, a Dify application, the MCP servers a client is configured with, a Compose application, the agents a framework’s configuration declares. The importer socket turns that foreign source into a running start on Aggrega authoring: it reads the source and scaffolds first-draft Aggregate and Component entities, and from an MCP configuration, a Compose application or a framework’s declared configuration a draft Release, for an author to review and finish, so a team carries what it already has forward into Aggrega rather than re-authoring it by hand. An importer maps meaning — it reads what a source node is and proposes the Aggrega entity that stands for it, or leaves it inside the flow the drafted platform carries; the compiler pipes the emitted entities through opaquely, exactly as it stays agnostic to what any plugin produces.

A format is a capability, not a compiler feature. An importer advertises the formats it handles as capabilities — import:langflow, import:flowise, import:n8n, import:mcp, import:compose, import:dify, import:crewai, import:langgraph, import:google-adk, import:agent-framework, and so on — and the host resolves an importer by the requested format, runs it, and takes back the entities it drafted. This is the same drop-in, capability-advertised model the parser socket takes with parse:<format>: the compiler core holds no built-in list of importable formats, so supporting a new one is shipping an importer plugin that advertises it, never a core release.

An importer reads through the parser socket; it does not re-parse. An importer needs the structured shape of its source, but it does not re-implement the reading of a format the ecosystem already parses. When it needs the tree, it asks the host to run the matching parser — the one the workspace’s catalog serves for the source’s syntax, or, where the catalog serves none, the one the compiler itself carries — through the same host-mediated parse capability the rest of the pipeline uses, and works from the JSON tree that comes back. Reading (syntax to tree) stays the parser’s job; mapping (tree to Aggrega entities) is the importer’s. The two sockets compose without duplicating each other: an importer adds the mapping intelligence for a source and leans on the existing parser for the bytes.

A format is recognised from what its importer declares, never guessed. An import may name its source format outright. Where it does not, the format is recognised from signatures each importer declares in its self-report and its Plugin entity records: the syntax a source is read in, the file names a signature applies to, and the paths the parsed tree must or must not carry. The host knows no format of its own. It parses the source through the parser the workspace’s catalog serves for each syntax a signature names — or the compiler’s own where the catalog serves none — evaluates the declared predicates over the tree that comes back, and reads the source as the format of the one importer whose signature matches. Declared signatures take the place a fixed file-extension map holds for the parser socket, because the formats an import reads can share an extension — a Langflow export, a Flowise export and an n8n workflow are all JSON files. A source no signature matches is refused, asking for the format and naming the formats the importers advertise — or, for a directory, asking for one of its files on its own or for a format whose importer declares file patterns, naming only those; a source that signatures of more than one format match is refused, naming them. Recognition reads nothing but the source and reaches no network, so recognising a new format is a declaration the new importer ships, never a change to the host. The rules for writing a signature are under The importer socket.

A directory is read through the files its importer declares. A source is a file or a directory. A file is handed to the importer whole. A directory is read into named sources — exactly the files of it that the file patterns of the importer’s signatures select, each named by its path inside the directory, in sorted order — and no other file of the directory is opened; a link that would lead the read out of the directory is refused before anything is read. An importer that declares no file patterns reads one file and refuses a directory, and a directory holding no file an importer’s patterns select is refused too. The compiler’s Langflow, Flowise, n8n, Dify and Agent Framework importers declare none, so each reads one exported flow, workflow or application file, or one declarative agent; its MCP importer declares the file names of the MCP client configurations it reads, so a project’s directory is read through the configurations it holds; its Compose importer declares the file names Compose reads by default, so a project’s directory is read through its Compose file and the override file Compose merges over it; and its CrewAI importer declares the file names a CrewAI project declares its agents and tasks under, so a project’s directory is read through those declarations and its program is never read; and its LangGraph importer declares langgraph.json, so an application’s directory is read through its configuration alone, its code and its environment files never read, an environment file the configuration names reaching the importer only where its attachment’s with.sources hands it, and then for the variables’ names alone; and its Google ADK importer declares root_agent.yaml, so an application’s directory is read through its root agent’s configuration alone, the configurations its sub-agents name reaching the importer only where its attachment’s with.sources hands them, and neither its code nor its environment file is ever read.

Mapping is deterministic, confidence-scored, and weighed against your own catalog. The host hands the importer a view of the Components the workspace’s own catalog holds — the catalog the importer was selected from — the workspace’s catalog folders, or, where it names none, the catalog snapshot its default registry publishes — an enterprise catalog’s Components exactly as the standard library’s. The view carries each Component’s name, version and labels, the key names its values and provides declare, and the selectors of its sockets, and never a value, a default or a secret; nothing is fetched for it beyond that snapshot, and its order is fixed, so one catalog yields one view. An importer built on the Go PDK’s importer package — the compiler’s own Langflow, Flowise, n8n and Compose importers among them — weighs each node in the source against those Components and nothing else, with a deterministic, no-model confidence model, and records the decision — the candidates it weighed, the match tier it assigned, and the choice it made — as reviewable hints an author can read and revise. A Component the catalog gains is a candidate on the next import, with no importer rebuilt. The default is hints only: the import proposes, and the author decides. A high-confidence match can be written as a reference to an existing catalog component instead of a freshly drafted body, but only when the operator opts in — always as an explicit, reversible suggestion the author gates, never a silent rewrite. Because the scoring carries no model and no runtime lookup, the same source scored against the same catalog always produces the same hints.

A flow is drafted as the platform that runs it. A Langflow flow, a Flowise chatflow and an n8n workflow run on a platform, and by default an import drafts that platform rather than the flow’s nodes: one instance of the standard library’s platform Component — core/ai-agent/langflow, core/ai-agent/flowise or core/ai-agent/n8n — carrying the flow as it was exported in its flow_definition value, which the platform loads at deploy. Each part of the flow a socket of the platform takes — on the standard library’s platforms, a model, an MCP server or another tool reached over HTTP, and a vector store — becomes a Component of its own, referenced or drafted as the mapping decides, and is wired to that socket under the platform’s uses. So each call the flow makes to a model, a tool or a store is a connection the Aggregate declares: a governance plugin judging the graph sees it as it sees any other edge, and the standard library’s egress allowlist, which the attach_egress_allowlist setting attaches to the platform, lets the platform connect only to what its connections reach, its own pods and the cluster’s DNS. Where the format lets it, the draft writes into the carried flow what makes the flow reach each part through its connection. Every other node — an agent, a chain, a trigger — stays inside the carried flow and becomes no Component, its decision recording the candidates it was weighed against. A Dify application is drafted the same way, in the form a whole installation takes: one entry of the Dify installation the standard library assembles, core/dify, carrying the application in its app_definition parameter, the installation wiring its own connections. The layout setting of the importer’s attachment chooses the draft: platform, the default, or nodes, which drafts every node of the source as a Component of its own, each edge of the flow a uses connection, and carries no flow. The platform carrying the flow sets out which nodes become parts and where each is wired.

A code-first framework is read through its declared configuration, never its program. CrewAI, LangGraph, Google ADK and Agent Framework keep an application’s behaviour in its program and declare its agents, graphs and models in configuration beside it. Their importers read only those declarations — a CrewAI project’s agent and task files, a LangGraph application’s langgraph.json, a Google ADK application’s agent configurations, an Agent Framework declarative agent — and draft the standard library’s agent for the framework around a program they never open, wired to what the declarations name: the model an agent asks for, where the agent’s model socket takes it, and the datastore a LangGraph checkpointer keeps state in. An MCP server an Agent Framework agent names is the model provider’s to reach, as a hosted tool, so the draft names it in comments and wires nothing to it. The program runs in the image the Release names. What only the program says — the logic of a task, a tool its code defines, an agent its code builds — is named in the draft’s comments and decisions and becomes no Component; carrying it into authoring files is the author’s work, by hand or with an AI assistant authoring on the author’s behalf through aggrega mcp, which reads the reference and scaffolds and validates entities.

What a source states about how its parts run lands in a draft Release. Operational inputs are the Release’s to supply, so the MCP, Compose, CrewAI, LangGraph, Google ADK and Agent Framework importers draft a Release beside the Aggregate, whose spec.aggregate names it: the Release carries what the source states — a server’s command line or address, a generic server’s image and port, a model’s endpoint — and, in comments above each entry, what the source states that no key of the drafted Component takes, such as a service’s volumes or a configuration’s environment. What no source states — the image running a framework’s program, the credential a connection presents, the Release’s metadata.environment and spec.manifest — is named in a comment where it belongs, for the operator to supply, and the build halts naming whichever of the image, the environment and the manifest is still unset. A platform draft writes no Release: the comment above the platform’s instance names what the Release supplies — the platform’s own inputs, such as the image it runs or its owner account, each wired MCP server’s address, and the credential each connection presents.

A credential value a source holds is carried as written unless its removal is asked for. An importer locates every value in its source that can carry a credential, each of one class: what the format marks as a credential, a member of an MCP server’s configuration, or an input the format marks as no credential that can carry one all the same, such as a request’s headers. By default none is written empty: each value holding something is carried as written — in the flow or application the platform carries, or in the draft Release — and named in a credential-carried warning by where it sits — its node, server, service or agent, and its field — never by its value, with the setting value that writes it empty. The empty_credentials setting turns removal on, a class at a time: marked writes empty what a format marks as a credential and every member of an MCP server’s configuration, and all the inputs marked as no credential as well, each value written empty reported with credential-emptied. What the draft writes so that a flow reaches its connection is wiring, written whatever the setting says, and a connection in the draft carries no credential: the Release attaches the one each connection presents. A file a source only points at, such as an environment file, is read for its variables’ names alone, where it is read at all, and a draft made node by node reads no value. What lies outside the places an importer locates — a custom component’s code, a prompt — is the author’s to review before sharing a draft, as Credential values the flow holds sets out.

The command, the editor and the assistant run one import. aggrega import <file or directory> runs an import from the terminal; the editor runs the same operation through its session’s aggrega/import request, and an AI assistant through the import tool of aggrega mcp. All three select the importer the same way, among the importers the workspace’s catalog holds and the compiler’s core importers: the one a plugins.importer attachment names, where it names one that advertises the format, and otherwise the highest version of the one importer advertising it — importers of two names for one format with neither attached stop the import, naming both, as Which importer turns a source into drafts sets out. All three report the mapping decisions beside the drafts. The command prints one line per mapped node on standard error, naming the Component or draft chosen for it, whether it is referenced or drafted, the match tier and, where the importer weighed a candidate, the best candidate’s score; the editor shows the same lines, and the editor session’s result and the assistant’s answer carry each decision in full. So an author sees where the import guessed, on whichever surface ran it, without opening the drafts. --format names the source format explicitly — for example langflow, flowise, n8n, mcp, compose, dify, crewai, langgraph, google-adk or agent-framework — in place of recognition. The command lays down the entities and any scaffold files the import produced beneath the workspace root, or beneath the directory --output-dir names; --dry-run does everything the command does except write, handing the drafted files back as content and naming the file each is for, so an author can review the scaffold before committing anything to the working tree.

The core importers. The core importers the compiler ships read these formats, one importer for each:

  • Langflow — a flow exported from Langflow, drafted as the standard library’s Langflow platform carrying the flow, each part of it a socket takes wired to that socket.
  • Flowise — a chatflow or an agentflow exported from Flowise, drafted as the standard library’s Flowise platform carrying it, each part of it a socket takes wired to that socket.
  • n8n — a workflow exported from n8n, drafted as the standard library’s n8n platform carrying it, each part of it a socket takes wired to that socket.
  • Dify — an application exported from Dify, drafted as the Dify installation the standard library assembles carrying the application, with the models, tools and knowledge bases it names reported as configured inside Dify.
  • MCP — an MCP client’s configuration or an MCP registry server description, each server drafted as an instance of the standard library’s MCP tool, with a Release carrying each server’s command line, address or image.
  • Compose — an infrastructure format, each service of a Compose application drafted as the catalog Component its image matches — through a table the importer carries, generated from the standard catalog’s Compose Recipes and Components when it is built — or as a generic server running its image, with a Release carrying each generic server’s image and port and, in comments, the ports, volumes and environment each service declares.
  • CrewAI — the agents a CrewAI project declares in its configuration files, each drafted as the standard library’s CrewAI agent carrying its role, goal and backstory and wired to the model it names, with the project’s tasks and tools reported as its program’s, the program itself never read, and a Release that leaves the image running it for the operator to name.
  • LangGraph — the graphs a LangGraph application’s configuration declares, each drafted as the standard library’s LangGraph agent carrying its graph’s import path and wired to the datastore its checkpointer keeps state in, with a Release stating, in a comment, the environment the configuration declares, and the graphs’ code never read.
  • Google ADK — the agent trees a Google ADK application’s agent configurations declare, each drafted as the standard library’s ADK agent wired to the model it names where ADK sends that model’s requests to the Gemini API, a model reached any other way — through a LiteLLM model string, say — named in a comment and its connection left for the author, with a Release that leaves the image running the application for the operator to name, and the application’s code never read.
  • Agent Framework — an Agent Framework declarative agent, drafted as the standard library’s Agent Framework agent wired to the OpenAI model it names, each MCP server it names written in comments since the model’s provider reaches it as a hosted tool, with a Release carrying the model’s endpoint and, in a comment, each server’s address, and the application’s code never read.

They are importer plugins like any other — the format-specific mapping intelligence lives in them, not in the core — built from the compiler’s sources and published with every compiler release at that release’s version. None is compiled into the binary: the binary carries each one’s Plugin entity and the digest of the one module it accepts, so each serves its format in every workspace with no catalog entry. The first import that needs one the machine does not hold fetches it from the workspace’s default registry, holds it to that digest, verifies it as a pull verifies a plugin it fetches — its signature under that registry’s trust policy, and the host functions it uses — and keeps it in the workspace’s content cache; every later import reads it from there, with no network for it. An import pins no importer: nothing else is written for it — no lockfile entry and no record of trusted plugins — and no pull caches it and no build reads it. A module that does not verify is refused, and nothing is kept. Where the module cannot be fetched — the workspace is offline, its registry cannot be reached, or the registry does not hold it — the import stops, naming the importer, its version and what puts its module on the machine. The choice stays the workspace’s: an importer its catalog holds under another name for one of these formats runs where a plugins.importer attachment names it, and one at the same name and version as a core importer runs in its place.

Seeding and Growing a Catalog

A catalog does not have to be built from nothing. Most of the work of seeding Recipes and plugins for a new environment is scaffolding and reuse rather than writing every binary by hand.

Importing a foreign source into draft authoring files. aggrega import <file or directory> reads a declarative agent-definition source — a Langflow or Flowise flow, an n8n workflow, or an MCP client’s configuration or registry server description — a Compose application, a Dify application, the agents a CrewAI project declares, the graphs a LangGraph application’s configuration declares, the agents a Google ADK application’s agent configurations declare, or an Agent Framework declarative agent, and scaffolds first-draft Aggregate and Component YAML, and from an MCP, a Compose, a CrewAI, a LangGraph, a Google ADK or an Agent Framework source a draft Release, for an author to review and finish, so a team carries forward what it already has rather than re-authoring it by hand. For each node of a flow, and each service of a Compose application, it scores the Components of the workspace’s own catalog — an enterprise catalog’s as much as the standard library’s — with a deterministic, no-model confidence model and records the decision — the candidates it weighed, the tier it assigned, and the choice it made — as reviewable hints, which the command, the editor and the assistant all report; a high-confidence match can be written as a catalog reference when the operator opts in, always as an explicit, reversible suggestion the author gates rather than a silent rewrite. Every Component a catalog gains is a candidate the next import weighs. The format-specific mapping intelligence lives in an importer plugin: the compiler’s own Langflow, Flowise, n8n, MCP, Compose, Dify, CrewAI, LangGraph, Google ADK and Agent Framework importers serve those formats in every workspace, fetched and verified on first use, and a catalog adds a format by holding an importer plugin that advertises it. A directory source is read through the file patterns its importer declares; the Langflow, Flowise, n8n, Dify and Agent Framework importers declare none, and each reads one exported file or declarative agent, while the MCP importer reads the client configurations a directory holds, the Compose importer its Compose files, merged as Compose merges them, the CrewAI importer a project’s declarations, never its program, the LangGraph importer an application’s configuration, never its code or an environment file — whose names it reads only where its attachment hands it the file — and the Google ADK importer an application’s root agent configuration, never its code or its environment file, its sub-agents’ configurations read where its attachment hands them — a configuration ADK states to be experimental, whose agents use a Gemini model by default and reach other providers’ models by name through classes of ADK’s own, or through a LiteLLM model string.

Most plugin work is templates, not compiled code. A large share of features only inject a static sidecar, environment variable, or label — a plain JSONPatch with no conditional logic. One configurable patcher plugin, written once to take a declarative JSONPatch template as its with input, can cover that common case without a unique compiled binary per feature: the author writes a template, and for many CRD-style targets a valuesMapping template (often referencing shared fragments in a MappingLibrary entry) is enough on its own. Purpose-written PDK plugins are for the genuinely conditional remainder.

Referencing established tools. When writing new plugin logic, authors can consult the publicly documented output shapes of established open-source tools — the structure of the CRDs, patches, or templates those tools are known to emit — as a reference for the target shape a new plugin must produce, while respecting each project’s license. Sidecar-injection webhooks, higher-level construct libraries, operator CRD generators, and trait or composition catalogs all publish output structures that map closely to what a comparable FeatureRecipe or plugin needs to emit. The goal is matching a well-understood output contract, not copying any project’s implementation.