feat(automation): add Pydantic schemas for the automation definition

Three layers of Pydantic models under app/automations/schemas/, one
file per concern (SRP), matching the envelope in
automation-design-plan.md §5.

definition/ — the editable envelope persisted in
automations.definition:
  - envelope.py       AutomationDefinition (top-level shape)
  - plan_step.py      PlanStep (one step in the sequential plan)
  - inputs.py         InputsBlock (the inputs JSON Schema wrapper)
  - execution.py      ExecutionBlock (timeouts, retries, concurrency,
                                      budget cap, on_failure plan)
  - metadata.py       MetadataBlock (tags + created_from_nl + extras)
  - trigger_spec.py   TriggerSpec (one entry in triggers[])

triggers/ — per-trigger config schemas, dispatched by registry on the
TriggerSpec.type discriminator:
  - schedule.py       ScheduleTriggerConfig(cron, timezone)
  - manual.py         ManualTriggerConfig() — empty in v1

actions/ — per-action config schemas, dispatched by registry on the
PlanStep.action discriminator:
  - agent_task.py     AgentTaskActionConfig(prompt, tools, model,
                                            output_schema)

Design properties verified by an inline smoke test:
  - The §5 worked example round-trips through model_validate_json /
    model_dump_json byte-for-byte (InputsBlock uses
    serialize_by_alias so the JSON key stays "schema" not
    "schema_").
  - Envelope rejects unknown top-level keys (extra="forbid").
  - MetadataBlock tolerates unknown keys (extra="allow").
  - ExecutionBlock defaults apply when the block is omitted.
  - retry_backoff and concurrency are typed as Literal — bogus
    values rejected at validation time.
  - Per-type configs enforce their required fields (cron + timezone
    on schedule; non-empty prompt on agent_task).

The envelope keeps trigger and action configs as untyped dicts on
purpose — per-type validation is a registry-driven dispatch (commit
10), keeping the envelope free of every-type-knows-every-type
coupling.

surfsense_backend/app/automations/schemas/definition/plan_step.py

@@ -0,0 +1,86 @@
+"""``PlanStep`` — one entry in the envelope's ``plan`` array."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class PlanStep(BaseModel):
+    """One step in an automation's sequential plan.
+
+    Steps run in array order, no parallelism, no DAGs, no loops. The
+    ``when`` Jinja expression provides conditional skip; branching is
+    achieved by ``when`` clauses on multiple steps. For looping or
+    parallel work, the user routes through ``agent_task`` and lets the
+    agent reason about it.
+
+    ``config`` is dispatched against the action registry at
+    validation time — its shape is determined by
+    ``ActionDefinition.config_schema`` for the ``action`` value.
+
+    ``output_as`` binds the step's typed output into the template
+    namespace for later steps, e.g. ``output_as: 'summary'`` then
+    ``{{ summary.bullets }}`` in a downstream step's config.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    step_id: str = Field(
+        ...,
+        description=(
+            "Unique-within-plan identifier. Used in run logs and as "
+            "the default for ``output_as`` when not provided."
+        ),
+        min_length=1,
+    )
+    action: str = Field(
+        ...,
+        description=(
+            "Action-type discriminator (e.g., ``agent_task``). "
+            "Resolved against the action registry."
+        ),
+        min_length=1,
+    )
+    when: str | None = Field(
+        default=None,
+        description=(
+            "Optional Jinja expression evaluated against the run "
+            "context. Step is skipped when the expression is "
+            "falsy."
+        ),
+    )
+    config: dict[str, Any] = Field(
+        default_factory=dict,
+        description=(
+            "Action-type-specific config. Validated against the "
+            "registered ``ActionDefinition.config_schema`` for "
+            "``action`` at definition-save time. Jinja templates "
+            "inside config are rendered at step-execute time."
+        ),
+    )
+    output_as: str | None = Field(
+        default=None,
+        description=(
+            "Name to bind the step output under for downstream "
+            "steps. Defaults to ``step_id`` when omitted."
+        ),
+    )
+    max_retries: int | None = Field(
+        default=None,
+        ge=0,
+        description=(
+            "Per-step override of the automation-level ``max_retries``. "
+            "Omitted means inherit from execution block."
+        ),
+    )
+    timeout_seconds: int | None = Field(
+        default=None,
+        gt=0,
+        description=(
+            "Per-step override of the automation-level "
+            "``timeout_seconds``. Omitted means inherit from "
+            "execution block."
+        ),
+    )