Automations

The Automations extension (automations) turns routine workflows across your cloud infrastructure into autonomous, reliable background executions. You define rules that react to platform signals — an incoming webhook, an alert from domain monitoring, a GitHub event, or a recurring cron schedule — and Webbee 🐝 executes the required multi-step actions across your connected extensions, infrastructure servers, and notification channels.

Everything can be driven conversationally or via declarative parameters: describe your operational intent in natural language, and Webbee formats, validates, and registers the rule with the platform execution engine.

Architecture & How It Works

Automations in Imperal Cloud are built for high availability and decoupled execution:

1. Event Sources & Triggers:

   • Time-based Schedules (Cron / Interval): Configured with standard cron expressions (e.g., 0 9 * * 1-5 for weekdays at 09:00 UTC) or human intervals (every 4 hours).
   • Platform Signals & Invariants: Fired when system metrics exceed thresholds, when audit events land, or when an extension records a lifecycle change.
   • External Webhooks & Connectors: Fired on GitHub commits/PRs, mail arrivals, Telegram messages, or third-party webhooks.

2. Durable Execution & Cooldown Guard:

   • Each rule is tracked with an optional cooldown_seconds window. Even if a flurry of events arrives simultaneously, executions are debounced to prevent spam and cascading load.
   • State, history, and trigger counters are preserved across executions. If an action temporarily fails due to a network blip, the platform's durable execution engine retries according to policy without dropping the run.

3. Contextual Action Dispatch:

   • When triggered, Webbee resolves the caller's authorized extension toolset and executes the action with the payload of the triggering event passed into context.

Creating and Editing Automations

Trigger Types & Format Examples

When registering an automation, you specify the trigger pattern:

• Cron Schedule:

  {
    "event_type": "schedule.cron",
    "schedule": "0 8 * * 1",
    "prompt": "Run a health audit on all connected domains and send the executive summary to Telegram channel #ops"
  }

• Interval:

  {
    "event_type": "schedule.interval",
    "schedule": "every 6 hours",
    "prompt": "Check SSL certificate expiration on all production hosts and warn if < 14 days remain"
  }

• Platform Event & Webhook:

  {
    "event_type": "github.pr_opened",
    "cooldown_seconds": 300,
    "prompt": "Run security scan and post the analysis as a PR comment"
  }

Viewing & Inspecting Automations

Controlling & Bulk Operations

Safe Multi-Rule Management

For large environments, bulk_automation_action allows dry-run evaluation:

# Preview what would be affected before applying changes
await ctx.extensions.call(
    "automations",
    "bulk_automation_action",
    action="pause",
    status="failing",
    dry_run=True,
)

Production Recipes & Best Practices

1. Daily Autonomous Ops Briefing

Schedule Webbee to compile infrastructure vitals, pending PRs, and server disk space every weekday morning at 08:30:

• Trigger: 30 8 * * 1-5
• Actions: Query web-tools:run_scan, github-connector:list_pull_requests, format Markdown digest, dispatch to telegram-publisher:post_to_channel.

2. Event-Driven Failover Alerting

Trigger immediate incident investigation when a health check probe fails:

• Trigger: monitoring.probe_failed
• Cooldown: 600 (10 minutes)
• Actions: Probing error logs via SSH connection, capturing real-time trace, and opening an incident ticket.

3. Automated Data Retention & Pruning

Weekly scheduled rotation of temporary logs and cache artifacts:

• Trigger: 0 3 * * 0 (Sundays at 03:00)
• Actions: Pruning stale transient records, archiving audit trails older than 90 days to cold storage.

Advanced Automation & Cross-Extension Piping (SDK 5.15)

In Imperal SDK 5.15 and ICNLI Cloud OS, automations advance from simple trigger-action pairs to declarative typed pipelines and reactive state synchronization.

1. Cross-Extension Typed Piping (@ext.pipe)

Extensions can declare pipes that stream outputs from one tool into another across the entire platform ecosystem:

from imperal_sdk import Extension, Pipe, PipeStep

ext = Extension("data-pipeline")

@ext.pipe("audit-to-telegram", description="Runs domain health audit and pipes summary to Telegram")
def audit_pipeline() -> Pipe:
    return Pipe([
        PipeStep(tool="web-tools.audit_domains", params={"domains": ["imperal.io", "webhostmost.com"]}),
        PipeStep(tool="mail.generate_summary", input_mapping={"raw_report": "step.0.data"}),
        PipeStep(tool="telegram-publisher.post_to_channel", input_mapping={"text": "step.1.summary", "channel": "@ops"})
    ])

2. Reactive State Signals (ctx.signals & @ext.signal)

Automations can react instantly to fine-grained state signals rather than polling or awaiting full cron cycles:

@ext.signal("deployment.completed")
async def on_deployment(ctx, key: str, value: dict):
    # Emit child signal or trigger compensating action
    await ctx.signals.emit("audit.trigger", {"service": value.get("service")})

3. Verifiable State Ledger & Time-Travel (ActionResult)

Every automated action records an immutable execution receipt with snapshot state. If an automated change fails mid-flight or requires rollback, the compensating action is invoked automatically:

from imperal_sdk.types import ActionResult

@ext.tool("resize_cluster")
async def resize_cluster(ctx, size: int) -> ActionResult:
    old_size = await get_cluster_size()
    await set_cluster_size(size)
    return ActionResult.success(
        data={"new_size": size},
        state_snapshot={"previous_size": old_size},
        compensating_action="restore_cluster_size",
        can_undo=True
    )