flowlit-integration 0.1.0__py3-none-any.whl

flowlit_integration/__init__.py

@@ -0,0 +1,26 @@
+"""flowlit-integration: reusable flowlit executors for common external
+systems (Harvest, Google Sheets, Gmail, Slack) and generic data output
+(spreadsheets), plus the shared `CredentialsProvider` abstraction they
+resolve their secrets through.
+
+This package sits in the middle of a three-tier hierarchy:
+
+    flowlit  ->  flowlit-integration  ->  <client application>
+
+`flowlit` is the execution engine (DAG plans, the `Executor` port, the
+`EventBus`) and has no knowledge of any specific external system.
+`flowlit-integration` knows how to talk to a handful of common ones, but
+nothing about any particular business's use of them. A client
+application (e.g. `ccq-automation`) imports the executors it needs from
+here, registers them with `flowlit` itself
+(`flowlit.register_executor(step_type, executor_instance)`), and wires
+them into its own business-specific DAGs.
+
+Registration is deliberately *not* automatic: importing this package, or
+any module in it, performs no registration and no I/O. A client calls
+`flowlit.register_executor(...)` explicitly for each executor it wants,
+the same way it would for an executor it wrote itself -- see each
+executor's own module docstring for its step-type name and spec shape.
+"""
+
+from __future__ import annotations

flowlit_integration/credentials/__init__.py

@@ -0,0 +1,10 @@
+"""The `CredentialsProvider` abstraction shared by every executor in this
+package: a small chain of sources (explicit value > environment variable
+> credentials file > future secret-manager extension point) plus typed,
+per-integration resolver functions.
+
+Populated by the "Move Generic Executors & Credentials Provider into
+flowlit-integration" task; currently empty scaffolding.
+"""
+
+from __future__ import annotations

flowlit_integration/credentials/provider.py

@@ -0,0 +1,419 @@
+"""Pluggable credential resolution, shared by every executor in this
+package.
+
+Why this exists
+----------------
+Originally written for a Google Sheets proof-of-concept that established
+a precedent worth keeping: try more than one source, in a defined order,
+and fall through silently to the next one rather than hard-failing on
+the first miss. Its precedence was, informally, *inline value > file
+path > environment variable*. Rather than re-implement that same
+fallback chain by hand in each executor (Harvest, Google Sheets, Gmail,
+Slack) — the kind of copy-paste that quietly drifts out of sync the
+moment one executor needs a fifth source — this module gives every
+executor one small, testable abstraction: :class:`CredentialsProvider`.
+
+Supported sources, and precedence
+----------------------------------
+A caller-supplied :class:`CredentialsProvider` (typically the one
+:func:`default_credentials_provider` builds) resolves a single named key
+(e.g. ``"HARVEST_TOKEN"``) by trying, in order:
+
+1. **Explicit / inline value** — not part of the provider chain at all:
+   any resolver function below (e.g. :func:`resolve_harvest_credentials`)
+   accepts the fully-resolved value as a keyword argument, and uses it
+   as-is, before ever consulting a provider. This is what lets a step
+   ``spec`` (or a test) hand in a credential directly, same as the POC's
+   own ``credentials_json``/``credentials_path`` spec fields do today.
+2. **Environment variable** — :class:`EnvCredentialsProvider`, reading
+   ``os.environ``.
+3. **Credentials file** — :class:`FileCredentialsProvider`, a flat JSON
+   object on disk (``{"HARVEST_TOKEN": "...", ...}``) — the standard
+   local-dev / container-mounted-secret pattern (a Docker/Kubernetes
+   secrets file, an Azure App Service "Configuration" file mount, etc.).
+4. **(Documented, not yet implemented) a cloud secret manager** — e.g.
+   Azure Key Vault or AWS Secrets Manager, for a client that deploys
+   there (see ``docs/credentials.md``). Adding it later means writing
+   one more ``CredentialsProvider`` and adding it to the chain
+   :func:`default_credentials_provider` builds — no executor changes.
+
+Sources 2–4 are what :class:`ChainedCredentialsProvider` implements:
+try each configured provider in order, return the first non-``None``
+hit. :func:`default_credentials_provider` is the single factory that
+builds "the" chain callers actually use — keeping it the one place a
+future source gets added.
+
+Nothing in this module logs a secret's *value* — only the key being
+looked up, and (for the file provider) the path being read. A missing
+credentials file is not an error here: it just means that source
+contributes nothing, so the chain falls through to the next one. A
+malformed one (not valid JSON, or not a flat object) *is* treated as a
+configuration bug and raises — silently ignoring a file that's actually
+present but broken would hide a real mistake.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+from abc import ABC, abstractmethod
+from collections.abc import Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+class MissingCredentialError(Exception):
+    """Raised by :meth:`CredentialsProvider.require` when `key` isn't
+    available from any configured source.
+
+    Carries `key` (never a resolved value) so callers/tests can assert
+    on *which* credential was missing without parsing the message.
+    """
+
+    def __init__(self, key: str) -> None:
+        self.key = key
+        super().__init__(
+            f"missing credential '{key}': not found in the environment, the "
+            "credentials file (if configured via FLOWLIT_INTEGRATION_CREDENTIALS_FILE), or any "
+            "other configured source. See docs/credentials.md."
+        )
+
+
+class CredentialsProvider(ABC):
+    """A source of named credential values.
+
+    `get()` is the one method a concrete source implements. `require()`
+    is a free convenience built on top of it — resolvers below use it so
+    a missing credential fails with one clear, typed error instead of a
+    `KeyError`/`TypeError` surfacing wherever the `None` first gets used.
+    """
+
+    @abstractmethod
+    def get(self, key: str) -> str | None:
+        """Return the value for `key`, or `None` if this source has
+        nothing for it. Never raises for an ordinary "not found" — that
+        is exactly what `None` means. A source-level failure that isn't
+        an ordinary miss (e.g. a credentials file that exists but isn't
+        valid JSON) may still raise.
+        """
+
+    def require(self, key: str) -> str:
+        """Like `get()`, but raises `MissingCredentialError` instead of
+        returning `None`."""
+        value = self.get(key)
+        if value is None:
+            raise MissingCredentialError(key)
+        return value
+
+
+class EnvCredentialsProvider(CredentialsProvider):
+    """Reads credentials from `os.environ`.
+
+    `prefix`, if given, is prepended to every key before the environment
+    lookup — e.g. `prefix="CCQ_"` makes `get("HARVEST_TOKEN")` read
+    `CCQ_HARVEST_TOKEN`. Defaults to no prefix, which is what every
+    resolver in this module actually uses (the documented env var names
+    in `docs/credentials.md` are read as-is).
+    """
+
+    def __init__(self, prefix: str = "") -> None:
+        self._prefix = prefix
+
+    def get(self, key: str) -> str | None:
+        return os.environ.get(f"{self._prefix}{key}")
+
+
+class FileCredentialsProvider(CredentialsProvider):
+    """Reads credentials from a flat JSON file: `{"KEY": "value", ...}`.
+
+    The file is read lazily, on first `get()`/`require()` call, and
+    cached for the lifetime of this instance — not at construction time,
+    so building one costs nothing and doesn't require the file to exist
+    yet (it may be mounted into a container after this provider is
+    constructed but before the first credential lookup, for example).
+
+    A missing file is treated as "no credentials from this source" —
+    `get()` returns `None` for every key, exactly as if the file were
+    present but empty — so a :class:`ChainedCredentialsProvider` falls
+    through to its next source rather than hard-failing. A file that
+    *exists* but isn't valid JSON, or isn't a flat `{str: str}` object,
+    raises `ValueError` — that's a real misconfiguration, not an absent
+    optional source.
+    """
+
+    def __init__(self, path: str | Path) -> None:
+        self._path = Path(path)
+        self._values: dict[str, str] | None = None
+
+    def _load(self) -> dict[str, str]:
+        if self._values is not None:
+            return self._values
+        if not self._path.is_file():
+            logger.debug("credentials file %s not found; skipping", self._path)
+            self._values = {}
+            return self._values
+        try:
+            raw = json.loads(self._path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError) as exc:
+            raise ValueError(f"credentials file {self._path} is not valid JSON: {exc}") from exc
+        if not isinstance(raw, dict) or not all(isinstance(v, str) for v in raw.values()):
+            raise ValueError(
+                f"credentials file {self._path} must be a flat JSON object of "
+                "string keys to string values"
+            )
+        logger.debug("loaded %d credential key(s) from %s", len(raw), self._path)
+        self._values = raw
+        return self._values
+
+    def get(self, key: str) -> str | None:
+        return self._load().get(key)
+
+
+class ChainedCredentialsProvider(CredentialsProvider):
+    """Tries a sequence of providers in order, returning the first hit.
+
+    This is the "more than one supply method" contract itself: each
+    configured provider is asked in turn, and the first one to return a
+    non-`None` value for `key` wins. An empty/absent source (e.g.
+    `FileCredentialsProvider` over a file that doesn't exist) simply
+    contributes nothing and the chain moves on — see
+    `default_credentials_provider` for the concrete order this package
+    uses by default.
+    """
+
+    def __init__(self, providers: Sequence[CredentialsProvider]) -> None:
+        self._providers = list(providers)
+
+    def get(self, key: str) -> str | None:
+        for provider in self._providers:
+            value = provider.get(key)
+            if value is not None:
+                return value
+        return None
+
+
+_CREDENTIALS_FILE_ENV_VAR = "FLOWLIT_INTEGRATION_CREDENTIALS_FILE"
+
+
+def default_credentials_provider() -> CredentialsProvider:
+    """Build the composite provider every executor resolves credentials
+    through, by default.
+
+    Order: environment variables, then — only if `FLOWLIT_INTEGRATION_CREDENTIALS_FILE`
+    names an existing file — that file. This is the single place a
+    future source (e.g. a cloud secret manager, for a client that needs
+    one) gets added: one more provider appended to the list
+    here, with no executor-level changes needed.
+
+    Callers that want a different order, an extra source, or a fixed set
+    of values (tests, mainly) can construct their own
+    `CredentialsProvider` instead — every executor accepts one via its
+    constructor, defaulting to this factory.
+    """
+    providers: list[CredentialsProvider] = [EnvCredentialsProvider()]
+    file_path = os.environ.get(_CREDENTIALS_FILE_ENV_VAR)
+    if file_path and os.path.isfile(file_path):
+        providers.append(FileCredentialsProvider(file_path))
+    return ChainedCredentialsProvider(providers)
+
+
+# --------------------------------------------------------------------------
+# Per-integration typed credentials + resolvers.
+#
+# Each dataclass documents exactly which keys it reads. The same names
+# are used both as environment variable names and as keys in the
+# credentials-file JSON, so the two sources are drop-in interchangeable
+# — moving from one to the other never means renaming anything.
+# --------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class HarvestCredentials:
+    """Harvest API v2 auth: a personal access token plus the account it
+    scopes requests to.
+
+    Reads (env var / credentials-file key):
+        HARVEST_TOKEN: the personal access token, sent as
+            ``Authorization: Bearer <token>``.
+        HARVEST_ACCOUNT_ID: sent as the ``Harvest-Account-ID`` header.
+    """
+
+    token: str
+    account_id: str
+
+
+def resolve_harvest_credentials(
+    provider: CredentialsProvider | None = None,
+    *,
+    token: str | None = None,
+    account_id: str | None = None,
+) -> HarvestCredentials:
+    """Resolve :class:`HarvestCredentials`.
+
+    `token`/`account_id`, if given, are used as-is (the "explicit /
+    inline" precedence tier — see the module docstring) and skip
+    `provider` entirely for that field. Otherwise falls back to
+    `provider` (defaulting to :func:`default_credentials_provider`),
+    which raises `MissingCredentialError` if the key isn't available
+    from any of its configured sources.
+    """
+    resolved_provider = provider if provider is not None else default_credentials_provider()
+    return HarvestCredentials(
+        token=token if token is not None else resolved_provider.require("HARVEST_TOKEN"),
+        account_id=(
+            account_id
+            if account_id is not None
+            else resolved_provider.require("HARVEST_ACCOUNT_ID")
+        ),
+    )
+
+
+@dataclass(frozen=True)
+class SlackCredentials:
+    """Slack Web API auth: a bot token.
+
+    Reads (env var / credentials-file key):
+        SLACK_BOT_TOKEN: sent as ``Authorization: Bearer <token>`` on
+            calls to Slack's Web API (e.g. ``chat.postMessage``).
+    """
+
+    bot_token: str
+
+
+def resolve_slack_credentials(
+    provider: CredentialsProvider | None = None,
+    *,
+    bot_token: str | None = None,
+) -> SlackCredentials:
+    """Resolve :class:`SlackCredentials`. See
+    :func:`resolve_harvest_credentials` for the explicit-value /
+    provider precedence this follows."""
+    resolved_provider = provider if provider is not None else default_credentials_provider()
+    return SlackCredentials(
+        bot_token=(
+            bot_token if bot_token is not None else resolved_provider.require("SLACK_BOT_TOKEN")
+        )
+    )
+
+
+# Deliberately not included here: a Slack *signing-secret* resolver (for
+# verifying inbound webhook requests). None of this package's executors
+# need it -- it's an inbound-transport concern, specific to whatever
+# client exposes a Slack webhook endpoint. A client needing it builds a
+# small resolver of its own on top of `CredentialsProvider`/
+# `default_credentials_provider` above, the same way this module's own
+# resolvers do -- see `docs/architecture.md`.
+
+
+@dataclass(frozen=True)
+class GmailCredentials:
+    """Gmail SMTP auth: a sending address plus an app password.
+
+    Reads (env var / credentials-file key):
+        GMAIL_SMTP_USERNAME: the full Gmail address to authenticate and
+            send as (e.g. ``reports@example.com``).
+        GMAIL_SMTP_APP_PASSWORD: a Google Account *app password* (not
+            the account's normal login password) — see
+            ``docs/credentials.md`` for how to generate one.
+    """
+
+    username: str
+    app_password: str
+
+
+def resolve_gmail_credentials(
+    provider: CredentialsProvider | None = None,
+    *,
+    username: str | None = None,
+    app_password: str | None = None,
+) -> GmailCredentials:
+    """Resolve :class:`GmailCredentials`. See
+    :func:`resolve_harvest_credentials` for the explicit-value /
+    provider precedence this follows."""
+    resolved_provider = provider if provider is not None else default_credentials_provider()
+    return GmailCredentials(
+        username=(
+            username
+            if username is not None
+            else resolved_provider.require("GMAIL_SMTP_USERNAME")
+        ),
+        app_password=(
+            app_password
+            if app_password is not None
+            else resolved_provider.require("GMAIL_SMTP_APP_PASSWORD")
+        ),
+    )
+
+
+@dataclass(frozen=True)
+class GoogleSheetsCredentials:
+    """Google service-account credentials for `gspread`.
+
+    Structurally different from the other three: a service-account
+    credential is a multi-field JSON document, not a single flat secret
+    string, so this holds *either* the inline JSON (as a string or an
+    already-parsed dict) *or* a file path to it — exactly the two forms
+    `google.oauth2.service_account.Credentials` already knows how to
+    load from (`from_service_account_info` / `from_service_account_file`)
+    — never both. `google_sheets_executor.py` does the actual parsing;
+    this dataclass only carries *which* form is available and where.
+
+    At most one of `credentials_json` / `credentials_path` is set. Both
+    `None` means: no credential was found from any source, including the
+    `GOOGLE_APPLICATION_CREDENTIALS` convention — callers fall back to
+    `gspread`'s own default discovery (`gspread.service_account()`),
+    matching the POC's behavior.
+    """
+
+    credentials_json: str | dict[str, Any] | None
+    credentials_path: str | None
+
+
+def resolve_google_sheets_credentials(
+    provider: CredentialsProvider | None = None,
+    *,
+    credentials_json: str | dict[str, Any] | None = None,
+    credentials_path: str | None = None,
+) -> GoogleSheetsCredentials:
+    """Resolve :class:`GoogleSheetsCredentials`, preserving the POC's
+    (`flowlite-client/google_sheet_executer.py`) precedence:
+
+    1. `credentials_json` — explicit inline JSON (string or dict) passed
+       by the caller (e.g. a step `spec` field). Used as-is.
+    2. `credentials_path` — explicit file path passed by the caller.
+       Used as-is (existence is checked when it's actually loaded).
+    3. `GOOGLE_CREDENTIALS_JSON` — inline JSON, resolved via `provider`
+       (env var or credentials file — either works, since a
+       `CredentialsProvider` doesn't care which source produced it).
+    4. `GOOGLE_APPLICATION_CREDENTIALS` — a file path, resolved via
+       `provider`. This is the same env var name Google's own client
+       libraries conventionally use (Application Default Credentials),
+       kept for drop-in compatibility with the POC and with any Google
+       tooling already configured in the environment.
+    5. Neither found: both fields come back `None` — the executor falls
+       back to `gspread.service_account()` (its own default local
+       discovery), exactly like the POC.
+
+    Only the *env var lookup* leg (steps 3–4) actually goes through
+    `provider` — the POC's own file-path/inline-JSON precedence (steps
+    1–2) is preserved as-is rather than being routed through the
+    provider chain, since those are per-call spec values, not named
+    secrets a `CredentialsProvider` source would hold.
+    """
+    if credentials_json is not None:
+        return GoogleSheetsCredentials(credentials_json=credentials_json, credentials_path=None)
+    if credentials_path is not None:
+        return GoogleSheetsCredentials(credentials_json=None, credentials_path=credentials_path)
+
+    resolved_provider = provider if provider is not None else default_credentials_provider()
+    env_json = resolved_provider.get("GOOGLE_CREDENTIALS_JSON")
+    if env_json is not None:
+        return GoogleSheetsCredentials(credentials_json=env_json, credentials_path=None)
+    env_path = resolved_provider.get("GOOGLE_APPLICATION_CREDENTIALS")
+    if env_path is not None:
+        return GoogleSheetsCredentials(credentials_json=None, credentials_path=env_path)
+    return GoogleSheetsCredentials(credentials_json=None, credentials_path=None)

flowlit_integration/executors/__init__.py

@@ -0,0 +1,10 @@
+"""Reusable flowlit executors, one per file, one per external system (or
+generic capability). Nothing in this package imports the others'
+optional third-party SDKs at module-import time beyond what that one
+executor needs -- see `pyproject.toml`'s per-integration extras.
+
+Populated by the "Move Generic Executors & Credentials Provider into
+flowlit-integration" task; currently empty scaffolding.
+"""
+
+from __future__ import annotations

flowlit_integration/executors/gmail_executor.py

@@ -0,0 +1,220 @@
+"""Gmail step executor: outbound email dispatch, with attachment support.
+
+Handles step type `"gmail"` once a client registers it (e.g.
+`flowlit.register_executor("gmail", GmailExecutor())` — see this
+package's own README/`docs/architecture.md`; registration is always the
+client's own explicit job, never automatic).
+
+Approach: SMTP via Gmail's SMTP endpoint (`smtp.gmail.com:587`,
+STARTTLS), authenticated with a Google Account *app password* — not
+`aiosmtplib` (a native-async SMTP library), and not full OAuth2. Chosen
+for three reasons, in order of weight:
+
+1. **Standard, well-documented practice for Gmail automation without the
+   OAuth consent-screen overhead.** An app password is a Google Account
+   feature purpose-built for exactly this (send mail as yourself from a
+   script/service account) — generate one under the account's Security
+   settings, no Google Cloud project, OAuth client, or consent screen
+   required. OAuth2 is the *better* answer for a multi-tenant product
+   sending on behalf of many different users' inboxes; this executor
+   sends from one fixed automation mailbox, which is exactly the case
+   app passwords are meant for.
+2. **`smtplib` is stdlib.** No extra dependency for what is, at bottom,
+   "connect, STARTTLS, log in, send" — one well-worn code path with
+   decades of Python usage behind it, versus a smaller, newer async-native
+   library. `aiosmtplib` would be a reasonable alternative if this
+   executor needed to hold many concurrent SMTP connections open at once;
+   it doesn't — sending one report/alert email per step is not a
+   throughput-sensitive path.
+3. **The blocking call is isolated, not ignored.** `smtplib.SMTP` is
+   synchronous, so every actual network call here runs inside
+   `asyncio.to_thread()` — same reasoning as `GoogleSheetsExecutor`
+   wrapping `gspread`: this process is a single-threaded, cooperative
+   event loop, and a blocking network call would freeze every other
+   concurrently-running step for as long as it takes.
+
+Credentials: `GMAIL_SMTP_USERNAME` (the sending address) and
+`GMAIL_SMTP_APP_PASSWORD` (the app password, *not* the account's normal
+login password), resolved via `flowlit_integration.credentials.provider.
+resolve_gmail_credentials` — see `config/credentials.py` for supported
+sources.
+
+Attachments are given as `{"filename": ..., "content_base64": ...}` —
+inline base64-encoded bytes, not a filesystem path. This keeps the
+executor's `spec` fully self-contained and serializable (a plan step's
+`spec` is plain JSON-compatible data flowing through flowlit's own
+output-placeholder substitution — e.g. a prior step's generated-report
+bytes, base64-encoded, feeding straight into this one) rather than
+depending on a shared filesystem between whatever step produced the
+attachment and this one, which would break the moment either runs on a
+different machine/container.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import binascii
+import smtplib
+from collections.abc import Mapping
+from email.mime.application import MIMEApplication
+from email.mime.multipart import MIMEMultipart
+from email.mime.text import MIMEText
+from typing import Any
+
+from flowlit.application.ports.executor import ExecutorResult
+from flowlit.infrastructure.executors.base_executor import BaseExecutor
+from pydantic import BaseModel, Field, field_validator
+
+from flowlit_integration.credentials.provider import CredentialsProvider, resolve_gmail_credentials
+
+_SMTP_HOST = "smtp.gmail.com"
+_SMTP_PORT = 587
+
+
+class GmailAttachment(BaseModel):
+    """One email attachment.
+
+    filename (string, required): attachment file name, as the recipient
+        will see it (e.g. `"timesheet_report.csv"`).
+    content_base64 (string, required): the attachment's bytes,
+        base64-encoded.
+    """
+
+    filename: str
+    content_base64: str
+
+    @field_validator("filename")
+    @classmethod
+    def _filename_not_blank(cls, value: str) -> str:
+        if not value.strip():
+            raise ValueError("must be a non-empty string")
+        return value
+
+
+class GmailSpec(BaseModel):
+    """Spec fields for a `"gmail"` step.
+
+    to (list of string, required): recipient email addresses.
+    subject (string, required): email subject line.
+    body (string, required): message body.
+    is_html (bool, optional): whether `body` is HTML rather than plain
+        text. Defaults to `False`.
+    attachments (list of `GmailAttachment`, optional): defaults to none.
+    cc (list of string, optional): CC recipients. Defaults to none.
+    """
+
+    to: list[str] = Field(min_length=1)
+    subject: str
+    body: str
+    is_html: bool = False
+    attachments: list[GmailAttachment] = Field(default_factory=list)
+    cc: list[str] = Field(default_factory=list)
+
+    @field_validator("to")
+    @classmethod
+    def _to_non_blank(cls, value: list[str]) -> list[str]:
+        if not all(addr.strip() for addr in value):
+            raise ValueError("must not contain blank addresses")
+        return value
+
+    @field_validator("subject")
+    @classmethod
+    def _subject_not_blank(cls, value: str) -> str:
+        if not value.strip():
+            raise ValueError("must be a non-empty string")
+        return value
+
+
+class GmailExecutor(BaseExecutor):
+    """Implements `flowlit.application.ports.executor.Executor` (via
+    `BaseExecutor`) for outbound Gmail dispatch. See module docstring
+    for the SMTP-via-app-password approach and why it was chosen.
+
+    Validated against `GmailSpec` (see `BaseExecutor.spec_model`).
+    """
+
+    spec_model = GmailSpec
+
+    def __init__(self, credentials_provider: CredentialsProvider | None = None) -> None:
+        super().__init__()
+        self._credentials_provider = credentials_provider
+
+    def _sync_send(self, spec: Mapping[str, Any], username: str, app_password: str) -> None:
+        """Build and send the MIME message. Runs inside `asyncio.to_thread`."""
+        message = MIMEMultipart()
+        message["From"] = username
+        message["To"] = ", ".join(spec["to"])
+        message["Subject"] = spec["subject"]
+        if spec.get("cc"):
+            message["Cc"] = ", ".join(spec["cc"])
+
+        body_subtype = "html" if spec.get("is_html") else "plain"
+        message.attach(MIMEText(spec["body"], body_subtype))
+
+        for attachment in spec.get("attachments", []):
+            part = MIMEApplication(base64.b64decode(attachment["content_base64"]))
+            part.add_header(
+                "Content-Disposition", "attachment", filename=attachment["filename"]
+            )
+            message.attach(part)
+
+        all_recipients = [*spec["to"], *spec.get("cc", [])]
+
+        with smtplib.SMTP(_SMTP_HOST, _SMTP_PORT, timeout=30) as smtp:
+            smtp.starttls()
+            smtp.login(username, app_password)
+            smtp.sendmail(username, all_recipients, message.as_string())
+
+    async def _run(self, step_id: str, spec: Mapping[str, Any]) -> ExecutorResult:
+        try:
+            credentials = resolve_gmail_credentials(self._credentials_provider)
+        except Exception as exc:  # MissingCredentialError, or a bad credentials file
+            self._logger.warning("step %s (gmail): credential resolution failed: %s", step_id, exc)
+            return ExecutorResult(success=False, error=f"Gmail credentials unavailable: {exc}")
+
+        for attachment in spec.get("attachments", []):
+            try:
+                base64.b64decode(attachment["content_base64"], validate=True)
+            except (binascii.Error, ValueError) as exc:
+                return ExecutorResult(
+                    success=False,
+                    error=(
+                        f"attachment '{attachment['filename']}' has invalid "
+                        f"base64 content: {exc}"
+                    ),
+                )
+
+        self._logger.info(
+            "step %s (gmail): sending '%s' to %d recipient(s)",
+            step_id,
+            spec["subject"],
+            len(spec["to"]),
+        )
+
+        try:
+            await asyncio.to_thread(
+                self._sync_send, spec, credentials.username, credentials.app_password
+            )
+        except smtplib.SMTPAuthenticationError as exc:
+            err_msg = f"Gmail SMTP authentication failed: {exc}"
+            self._logger.warning("step %s (gmail): %s", step_id, err_msg)
+            return ExecutorResult(success=False, error=err_msg)
+        except smtplib.SMTPException as exc:
+            err_msg = f"Gmail SMTP error: {type(exc).__name__}: {exc}"
+            self._logger.warning("step %s (gmail): %s", step_id, err_msg)
+            return ExecutorResult(success=False, error=err_msg)
+        except OSError as exc:
+            err_msg = f"Could not connect to {_SMTP_HOST}:{_SMTP_PORT}: {exc}"
+            self._logger.warning("step %s (gmail): %s", step_id, err_msg)
+            return ExecutorResult(success=False, error=err_msg)
+
+        self._logger.info("step %s (gmail): sent '%s'", step_id, spec["subject"])
+        return ExecutorResult(
+            success=True,
+            output={
+                "to": spec["to"],
+                "subject": spec["subject"],
+                "attachment_count": len(spec.get("attachments", [])),
+            },
+        )