Developer Preview: These docs describe the contract Atomical plans to support for plugin authors. Marketplace upload, sandbox distribution, and long-term version negotiation are not available yet.
Core model
An automation plugin teaches an Atomical agent how to use a provider. Atomical owns the agent identity, profile, OTP and resource services, and managed runtime. The plugin owns provider-specific setup, recovery, and skills.
The lifecycle has one main loop.
setup -> active -> skill -> recover -> active | failedSetup prepares the provider account. Active means skills can run against that same account. A skill may find that the session expired or a provider check changed; in that case it returns a recoverable error and the runtime can call recover. Recovery either gets the account back to active or returns failed with a stable error code.
What plugins provide
- A manifest that declares the provider, runtime range, capabilities, sender domains, and skills.
- A
setuphandler for first-time account preparation. - An optional
recoverhandler for logged-out or interrupted provider accounts. - Skills that expose stable actions such as
check_status,update_profile, orsubmit_request. - Provider helpers that keep API calls, browser interaction, and parsing details behind the plugin boundary.
What Atomical provides
- Agent identity: provider-facing email, phone when available, and public agent identity.
- Managed browser profile: persistent provider account and session context.
- OTP inbox: routed email and SMS code access.
- Managed resources: payment method today, more resource types later.
- Scoped plugin state for resumable checkpoints the provider would recognize.
- Structured logs for user-facing audit events.
The rest of this section keeps the public contract provider-neutral. Provider details belong inside the plugin.