Nodes, tools, and events
A contribution is a maintained public interface. Do not create artificial symmetry between nodes, tools, and APIs: each surface is optimized for a different mode of use.
Process nodes
A node is designed to be composed in a graph: typed parameters and outputs, explicit bindings, routes, and guarantees visible to the process author.
Add a node when a durable business use case justifies the surface. The mere existence of a provider endpoint or CRUD operation is not sufficient justification.
Agent tools
A Tool is designed to be selected and invoked by an Agent. Its intent, arguments, and result must be adapted to that interaction rather than copied from a node.
The tool catalog is deliberately curated: an operation may exist as a node or API without an equivalent Tool being desirable.
Events
An extension event exposes to Ormuz a meaningful occurrence in the partner system. Its identifier and typed inputs must remain stable and describe what happened, not the internal processing used to ingest it.
- prefer a precise business event over a generic webhook that is difficult to use;
- expose platform objects only when their resolution is reliable and legitimate;
- keep an external object when the fact belongs to the partner system;
- do not turn an inbound event into a hidden mutation of a platform object.
User Journey actions
A User Journey action is a browser contribution intended for the participant: embedded component, provider interaction, or redirect with resume. It must be namespaced by the extension and respect the strict lifecycle of the current action.
This surface is not an additional node: the node defines the process operation, while the action provides the associated participant-facing experience when that operation waits for an interaction.
Process templates
A process template is a distinct marketplace artifact that provides a ready-to-customize process and declares the extensions it depends on. It is not a workflows field under spec.contributes in the extension manifest.
Associate a template with an extension through its requirements.extensions and, when installation must select a configuration, through its requirements.configuration_slots. The template remains versioned and installable as its own artifact: the extension provides the capabilities, the template demonstrates a reusable composition.
Choose the right contribution
| Need | Suitable surface |
|---|---|
| The process author must explicitly compose an operation with other steps. | Node |
| An Agent must have a bounded, selectable capability. | Tool |
| The external system announces that a fact occurred. | Event |
| The participant must interact with a UI or redirect provided by the extension. | User Journey action |
| A reusable composition must be distributed as a ready-to-customize process. | Process template, a marketplace artifact distinct from the extension. |
| The need is simply to read or write through a public machine contract. | API, without automatically creating a node or Tool. |