dex-connector-google-gmail 0.1.0__tar.gz

dex_connector_google_gmail-0.1.0/.gitignore

@@ -0,0 +1,2 @@
+/dist/dex_connector_google_gmail-0.1.0-py3-none-any.whl
+/dist/dex_connector_google_gmail-0.1.0.tar.gz

dex_connector_google_gmail-0.1.0/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.5
+Name: dex-connector-google-gmail
+Version: 0.1.0
+Summary: Dex-native Python connector for Gmail
+License-Expression: MIT
+Requires-Python: >=3.11
+Requires-Dist: dex-connectors-sdk==0.1.0
+Requires-Dist: dex-python-sdk>=1.28.0
+Requires-Dist: httpx>=0.27
+Description-Content-Type: text/markdown
+
+# Gmail connector for Python
+
+`dex-connector-google-gmail` provides typed Gmail reads, sends, and replies for
+Dex Python Flows. The package imports as `dex_connectors.google_gmail`.
+Version 0.1.0 includes `getMessage`, `sendMessage`, and `replyToMessage` only;
+the Go `messageReceived` and `replyReceived` Triggers are not available in Python.
+
+## Install
+
+After release, install `dex-connector-google-gmail==0.1.0`. The package requires
+`dex-connectors-sdk==0.1.0` and `dex-python-sdk>=1.28.0`; the latter provides
+Go-compatible JSON field metadata and the Flow start and attempt deadline
+needed for Gmail's duplicate-send fence.
+
+## Configure a connection
+
+Use one static connection name in the Flow and in Dex Web **Connections**.
+Select Google OAuth for a personal Gmail or ordinary Workspace mailbox. In
+[Google Cloud Console](https://console.cloud.google.com/apis/credentials),
+enable Gmail API, configure the consent screen, register the exact Dex redirect
+URI on a Web application, then grant `openid`, UserInfo email, Gmail read-only,
+and Gmail send scopes. Dex derives the verified primary email and stores the
+access and refresh tokens in encrypted project storage. Its connection provider
+coordinates token refresh and persists rotated refresh tokens. A service-account
+key with Workspace domain-wide delegation is the administrator-only alternative.
+
+The Python connector uses the same manifest authorization guide and safe
+defaults as the Go connector. Dex CLI/Web 1.28.0 supports Python Flow
+analysis, and the package includes generated `dex-connector.json` for Dex Web
+connection discovery. Dex Web authorization has not been live-verified with
+this package. Do not put access tokens, refresh tokens, or service-account
+keys in Flow input, results, Attributes, Streams, logs, or mock reports.
+
+## Run the example
+
+[`examples/thread_reply`](examples/thread_reply/main.py) reads one received
+message, replies in its existing thread, and completes with the accepted reply
+IDs. Its Worker loads the `gmail-inbox` connection from the Dex Web project
+configuration. Factory calls keep their connection name and annotation fields
+inline so Dex CLI can read the Flow definition; the factories also accept
+`StepAnnotations` for programmatic construction. Dex CLI 1.28.1 is needed for
+strict FDG analysis of this example's local Steps routing into connector Steps
+(tracked in Dex issue #362). The entrypoint uses the public connection and Step
+APIs:
+
+```python
+connection = new_project_connection(project, CONNECTION_NAME)
+await run_thread_reply_worker(
+    ThreadReplyFlow(connection),
+    os.environ.get("DEX_BLOB_CACHE_DIRECTORY", "/tmp/dex-gmail-thread-reply-cache"),
+    os.environ.get("DEX_SERVER_ADDRESS", "localhost:8801"),
+)
+```
+
+Run `dexcli dev`, then from this `python/` directory run
+`DEX_CONNECTOR_CONFIG_FILE=/path/to/connections.json python -m examples.thread_reply.main`.
+The Flow type is `ThreadReplyFlow`; its input JSON contains `messageId` and
+`replyText`. Use a real mailbox message ID and a reply body with no secrets.
+The [integration test](examples/thread_reply/tests/test_integration.py) runs
+the same Flow on a real Dex Worker and Client with a local fake Gmail HTTP
+boundary and manifest mocks.
+
+## Send confirmation
+
+Gmail does not deduplicate messages by `Message-ID`. The connector derives a
+stable run-specific RFC Message-ID from the Dex Call key, run ID, and Flow start
+second. Its Python Mutation Steps use the manifest's asynchronous Execute
+durability and persist the single-dispatch heartbeat before a POST. On a
+numbered retry it searches Sent Mail first. A prior claimed send can only be
+read back; a second POST requires a persisted `notSent` or `canResend` marker.
+After a possibly accepted POST loses its answer or returns 5xx, the connector
+polls Sent Mail before returning Retry. A successful 2xx is already accepted
+even if its response is malformed, oversized, or unreadable; a Sent Mail miss
+then returns `sent` with an empty message ID. A search miss after a claimed
+POST remains Retry without another dispatch; the Flow fails when its retry
+budget is exhausted. A definite 429 or 503 refusal, or a transport failure
+proven to precede dispatch, permits a later send. The manifest limits sends
+and replies to five attempts within two minutes.
+
+Live provider authorization and these Gmail behaviors remain unverified without
+a user-controlled account: retention of the client-set Message-ID header,
+`rfc822msgid` search matching, and Sent Mail indexing latency. No live provider
+credentials are included in this package.

dex_connector_google_gmail-0.1.0/README.md

@@ -0,0 +1,83 @@
+# Gmail connector for Python
+
+`dex-connector-google-gmail` provides typed Gmail reads, sends, and replies for
+Dex Python Flows. The package imports as `dex_connectors.google_gmail`.
+Version 0.1.0 includes `getMessage`, `sendMessage`, and `replyToMessage` only;
+the Go `messageReceived` and `replyReceived` Triggers are not available in Python.
+
+## Install
+
+After release, install `dex-connector-google-gmail==0.1.0`. The package requires
+`dex-connectors-sdk==0.1.0` and `dex-python-sdk>=1.28.0`; the latter provides
+Go-compatible JSON field metadata and the Flow start and attempt deadline
+needed for Gmail's duplicate-send fence.
+
+## Configure a connection
+
+Use one static connection name in the Flow and in Dex Web **Connections**.
+Select Google OAuth for a personal Gmail or ordinary Workspace mailbox. In
+[Google Cloud Console](https://console.cloud.google.com/apis/credentials),
+enable Gmail API, configure the consent screen, register the exact Dex redirect
+URI on a Web application, then grant `openid`, UserInfo email, Gmail read-only,
+and Gmail send scopes. Dex derives the verified primary email and stores the
+access and refresh tokens in encrypted project storage. Its connection provider
+coordinates token refresh and persists rotated refresh tokens. A service-account
+key with Workspace domain-wide delegation is the administrator-only alternative.
+
+The Python connector uses the same manifest authorization guide and safe
+defaults as the Go connector. Dex CLI/Web 1.28.0 supports Python Flow
+analysis, and the package includes generated `dex-connector.json` for Dex Web
+connection discovery. Dex Web authorization has not been live-verified with
+this package. Do not put access tokens, refresh tokens, or service-account
+keys in Flow input, results, Attributes, Streams, logs, or mock reports.
+
+## Run the example
+
+[`examples/thread_reply`](examples/thread_reply/main.py) reads one received
+message, replies in its existing thread, and completes with the accepted reply
+IDs. Its Worker loads the `gmail-inbox` connection from the Dex Web project
+configuration. Factory calls keep their connection name and annotation fields
+inline so Dex CLI can read the Flow definition; the factories also accept
+`StepAnnotations` for programmatic construction. Dex CLI 1.28.1 is needed for
+strict FDG analysis of this example's local Steps routing into connector Steps
+(tracked in Dex issue #362). The entrypoint uses the public connection and Step
+APIs:
+
+```python
+connection = new_project_connection(project, CONNECTION_NAME)
+await run_thread_reply_worker(
+    ThreadReplyFlow(connection),
+    os.environ.get("DEX_BLOB_CACHE_DIRECTORY", "/tmp/dex-gmail-thread-reply-cache"),
+    os.environ.get("DEX_SERVER_ADDRESS", "localhost:8801"),
+)
+```
+
+Run `dexcli dev`, then from this `python/` directory run
+`DEX_CONNECTOR_CONFIG_FILE=/path/to/connections.json python -m examples.thread_reply.main`.
+The Flow type is `ThreadReplyFlow`; its input JSON contains `messageId` and
+`replyText`. Use a real mailbox message ID and a reply body with no secrets.
+The [integration test](examples/thread_reply/tests/test_integration.py) runs
+the same Flow on a real Dex Worker and Client with a local fake Gmail HTTP
+boundary and manifest mocks.
+
+## Send confirmation
+
+Gmail does not deduplicate messages by `Message-ID`. The connector derives a
+stable run-specific RFC Message-ID from the Dex Call key, run ID, and Flow start
+second. Its Python Mutation Steps use the manifest's asynchronous Execute
+durability and persist the single-dispatch heartbeat before a POST. On a
+numbered retry it searches Sent Mail first. A prior claimed send can only be
+read back; a second POST requires a persisted `notSent` or `canResend` marker.
+After a possibly accepted POST loses its answer or returns 5xx, the connector
+polls Sent Mail before returning Retry. A successful 2xx is already accepted
+even if its response is malformed, oversized, or unreadable; a Sent Mail miss
+then returns `sent` with an empty message ID. A search miss after a claimed
+POST remains Retry without another dispatch; the Flow fails when its retry
+budget is exhausted. A definite 429 or 503 refusal, or a transport failure
+proven to precede dispatch, permits a later send. The manifest limits sends
+and replies to five attempts within two minutes.
+
+Live provider authorization and these Gmail behaviors remain unverified without
+a user-controlled account: retention of the client-set Message-ID header,
+`rfc822msgid` search matching, and Sent Mail indexing latency. No live provider
+credentials are included in this package.

dex_connector_google_gmail-0.1.0/examples/thread_reply/__init__.py

@@ -0,0 +1,3 @@
+# Copyright (c) 2026 Super Durable
+# SPDX-License-Identifier: MIT
+"""Gmail message read-and-reply example Flow."""

dex_connector_google_gmail-0.1.0/examples/thread_reply/flow.py

@@ -0,0 +1,111 @@
+# Copyright (c) 2026 Super Durable
+# SPDX-License-Identifier: MIT
+"""Read one Gmail message and reply in its existing thread with Dex Steps."""
+
+import dex
+from dex_connectors.sdk import MutationResult, QueryResult, QueryStep
+
+from dex_connectors.google_gmail import (
+    Connection,
+    GetMessageInput,
+    Message,
+    ReplyToMessageInput,
+    SendMessageOutput,
+    new_get_message_step,
+    new_reply_to_message_step,
+)
+
+from .models import CONNECTION_NAME, ThreadReplyInput, ThreadReplyOutput
+
+_REPLY_TEXT = dex.Attribute("gmail-thread-reply-text", str)
+
+
+# dex:group group-id:gmail group-label:"Gmail"
+# dex:explanation text:"Complete after Gmail confirms the threaded reply was sent."
+class ReplySent(dex.Step[MutationResult[SendMessageOutput]]):
+    """Complete after Gmail definitely accepts the threaded reply."""
+
+    async def execute(  # type: ignore[override]
+        self, context: dex.AsyncContext, input: MutationResult[SendMessageOutput]
+    ) -> dex.StepDecision:
+        """Return provider reply IDs without credentials or message bodies."""
+        return dex.graceful_complete(
+            ThreadReplyOutput(input.value.thread_id, input.value.message_id)
+        )
+
+
+# dex:group group-id:gmail group-label:"Gmail"
+# dex:explanation text:"Route a successful source message read to the threaded reply."
+class MessageRead(dex.Step[QueryResult[Message]]):
+    """Send the reply after a successful source-message read."""
+
+    async def execute(  # type: ignore[override]
+        self, context: dex.AsyncContext, input: QueryResult[Message]
+    ) -> dex.StepDecision:
+        """Reuse the source ID and the reply text stored at Flow admission."""
+        return dex.go_to(
+            dex.StepRef("ReplyToReceivedEmail"),
+            ReplyToMessageInput(input.value.message_id, _REPLY_TEXT.get(context)),
+        )
+
+
+# dex:group group-id:gmail group-label:"Gmail"
+# dex:explanation text:"Validate the request and retain reply text before reading Gmail."
+class PrepareReply(dex.Step[ThreadReplyInput]):
+    """Persist the reply text before the Gmail query Step starts."""
+
+    async def execute(  # type: ignore[override]
+        self, context: dex.AsyncContext, input: ThreadReplyInput
+    ) -> dex.StepDecision:
+        """Reject blank input and carry the source ID into getMessage."""
+        if not input.message_id.strip() or not input.reply_text.strip():
+            return dex.force_fail("Gmail message ID and reply text are required")
+        _REPLY_TEXT.set(context, input.reply_text)
+        return dex.go_to(dex.StepRef("ReadReceivedEmail"), input)
+
+
+class ThreadReplyFlow(dex.Flow[ThreadReplyInput]):
+    """Demonstrate getMessage and replyToMessage with one static Gmail connection."""
+
+    def __init__(self, connection: Connection) -> None:
+        if connection.reference.name != CONNECTION_NAME:
+            raise ValueError("Gmail Flow requires the static gmail-inbox connection")
+        self.reply_sent = ReplySent()
+        self.reply = new_reply_to_message_step(
+            step_type="ReplyToReceivedEmail",
+            step_input_type=ReplyToMessageInput,
+            annotations={
+                "groupId": "gmail",
+                "groupLabel": "Gmail",
+                "explanation": "Reply in the received message's thread.",
+            },
+            connection=connection,
+            connection_name="gmail-inbox",
+            map_to_operation_input=lambda value: value,
+            sent=self.reply_sent,
+        )
+        self.message_read = MessageRead()
+        self.read: QueryStep[ThreadReplyInput, GetMessageInput, Message] = new_get_message_step(
+            step_type="ReadReceivedEmail",
+            step_input_type=ThreadReplyInput,
+            annotations={
+                "groupId": "gmail",
+                "groupLabel": "Gmail",
+                "explanation": "Read the source Gmail message.",
+            },
+            connection=connection,
+            connection_name="gmail-inbox",
+            map_to_operation_input=lambda value: GetMessageInput(value.message_id),
+            read=self.message_read,
+        )
+        self.prepare = PrepareReply()
+
+    def get_steps(self) -> dex.StepList[ThreadReplyInput]:
+        """Register each Step instance once under its stable Dex identity."""
+        return dex.StepList.start_step(self.prepare).other_steps(
+            self.read, self.message_read, self.reply, self.reply_sent
+        )
+
+    def get_persistence_schema(self) -> dex.PersistenceSchema:
+        """Persist only the non-secret reply text required after the read Step."""
+        return dex.PersistenceSchema.of(_REPLY_TEXT)

dex_connector_google_gmail-0.1.0/examples/thread_reply/main.py

@@ -0,0 +1,35 @@
+# Copyright (c) 2026 Super Durable
+# SPDX-License-Identifier: MIT
+"""Run the Gmail read-and-reply example against Dex and one named connection."""
+
+import asyncio
+import os
+
+from dex_connectors.sdk.projectconfig import load_from_environment
+
+from dex_connectors.google_gmail import Connection, new_project_connection
+
+from .flow import ThreadReplyFlow
+from .models import CONNECTION_NAME
+from .worker import run_thread_reply_worker
+
+
+async def main() -> None:
+    """Load Dex Web connection material and serve one Flow on a pull Worker."""
+    project = await load_from_environment()
+    connection: Connection | None = None
+    try:
+        connection = new_project_connection(project, CONNECTION_NAME)
+        await run_thread_reply_worker(
+            ThreadReplyFlow(connection),
+            os.environ.get("DEX_BLOB_CACHE_DIRECTORY", "/tmp/dex-gmail-thread-reply-cache"),
+            os.environ.get("DEX_SERVER_ADDRESS", "localhost:8801"),
+        )
+    finally:
+        if connection is not None:
+            await connection.close()
+        await project.close()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

dex_connector_google_gmail-0.1.0/examples/thread_reply/models.py

@@ -0,0 +1,27 @@
+# Copyright (c) 2026 Super Durable
+# SPDX-License-Identifier: MIT
+"""Typed input and output for the Gmail read-and-reply example Flow."""
+
+from dataclasses import dataclass, field
+
+CONNECTION_NAME = "gmail-inbox"
+
+
+@dataclass(frozen=True, slots=True)
+class ThreadReplyInput:
+    """Identify a received Gmail message and the plain-text reply to send."""
+
+    # Provider message identifier read before replying.
+    message_id: str = field(metadata={"dex_json_name": "messageId"})
+    # Reply body sent to the message's Reply-To or From mailbox.
+    reply_text: str = field(metadata={"dex_json_name": "replyText"})
+
+
+@dataclass(frozen=True, slots=True)
+class ThreadReplyOutput:
+    """Return the read source and accepted reply IDs after the Flow completes."""
+
+    # Gmail thread shared by source and reply.
+    thread_id: str = field(metadata={"dex_json_name": "threadId"})
+    # Gmail identifier of the accepted reply; it can be empty after an unusable accepted response.
+    reply_message_id: str = field(metadata={"dex_json_name": "replyMessageId"})

dex_connector_google_gmail-0.1.0/examples/thread_reply/tests/test_integration.py

@@ -0,0 +1,254 @@
+# Copyright (c) 2026 Super Durable
+# SPDX-License-Identifier: MIT
+"""Real Dex Worker and Client coverage for the Gmail read-and-reply Flow."""
+
+import asyncio
+import json
+import os
+from collections.abc import Callable
+from datetime import timedelta
+from pathlib import Path
+from typing import TypeVar
+from uuid import uuid4
+
+import dex
+import httpx
+import pytest
+from dex_connectors.sdk import (
+    ConnectionRef,
+    MutationResult,
+    SecretString,
+    StaticCredentialProvider,
+    StepAnnotations,
+)
+
+from dex_connectors.google_gmail import (
+    Config,
+    Connection,
+    Credentials,
+    GmailProvider,
+    SendMessageInput,
+    SendMessageOutput,
+    new_connection,
+    new_send_message_step,
+)
+from dex_connectors.google_gmail.gmailmock import Mock
+from examples.thread_reply.flow import ThreadReplyFlow
+from examples.thread_reply.models import CONNECTION_NAME, ThreadReplyInput, ThreadReplyOutput
+
+FlowInput = TypeVar("FlowInput")
+
+
+async def _run_flow(
+    connection: Connection,
+    input_value: ThreadReplyInput,
+    cache_directory: Path,
+) -> dex.FlowResult:
+    """Run the checked-in example Flow against a real Dex Worker and Client."""
+    return await _run_registered_flow(ThreadReplyFlow(connection), input_value, cache_directory)
+
+
+async def _run_registered_flow(
+    flow: dex.Flow[FlowInput], input_value: FlowInput, cache_directory: Path
+) -> dex.FlowResult:
+    """Start one unique Flow and wait for its actual terminal Dex result."""
+    server_address = os.environ.get("DEX_SERVER_ADDRESS", "localhost:8801")
+    blob_cache = dex.open_blob_cache(dex.BlobCacheConfig(str(cache_directory), 64 * 1024 * 1024))
+    registry = dex.Registry([flow], allow_async_handlers=True)
+    worker = dex.AsyncWorker(registry, blob_cache, dex.WorkerOptions(server_address=server_address))
+    client = dex.AsyncClient(registry, blob_cache, dex.ClientOptions(server_address=server_address))
+    worker_task = asyncio.create_task(worker.start())
+    try:
+        await worker.wait_pull_registered(timeout=30)
+        flow_id = f"gmail-python-integ-{uuid4().hex}"
+        await client.start_flow(flow, flow_id, input_value)
+        return await client.wait_for_flow(flow_id, timeout=timedelta(seconds=40))
+    finally:
+        await client.close()
+        await worker.close()
+        await worker_task
+        blob_cache.close()
+
+
+def _source_response() -> httpx.Response:
+    return httpx.Response(
+        200,
+        json={
+            "id": "source-1",
+            "threadId": "thread-1",
+            "internalDate": "1772615700000",
+            "payload": {
+                "headers": [
+                    {"name": "From", "value": "Ada <ada@example.com>"},
+                    {"name": "Message-ID", "value": "<source@example.com>"},
+                    {"name": "Subject", "value": "Question"},
+                ]
+            },
+        },
+    )
+
+
+async def _provider_flow(
+    respond: Callable[[httpx.Request], httpx.Response],
+    input_value: ThreadReplyInput,
+    cache_directory: Path,
+) -> dex.FlowResult:
+    """Use a fake Gmail HTTP boundary with a real Dex Worker and Client."""
+    credential = Credentials(SecretString("inert-access"), "owner@example.org")
+    credentials = StaticCredentialProvider({ConnectionRef("google", CONNECTION_NAME): credential})
+    async with httpx.AsyncClient(transport=httpx.MockTransport(respond)) as http_client:
+        provider = GmailProvider(
+            Config(endpoint="http://localhost/gmail/v1"), credentials, http_client=http_client
+        )
+        return await _run_flow(
+            new_connection(provider, ConnectionRef("google", CONNECTION_NAME)), input_value,
+            cache_directory,
+        )
+
+
+@pytest.mark.asyncio
+async def test_real_dex_retries_read_then_sends_one_threaded_reply(tmp_path: Path) -> None:
+    """Dex retries the Query Step, then the Mutation Step confirms one reply."""
+    requests: list[str] = []
+
+    def respond(request: httpx.Request) -> httpx.Response:
+        request_kind = request.url.params.get("format", "POST") if request.method == "GET" else "POST"
+        requests.append(request_kind)
+        if request_kind == "full" and requests.count("full") == 1:
+            return httpx.Response(503)
+        if request.method == "GET":
+            return _source_response()
+        payload = json.loads(request.content)
+        assert payload["threadId"] == "thread-1"
+        return httpx.Response(200, json={"id": "reply-1", "threadId": "thread-1"})
+
+    result = await _provider_flow(
+        respond, ThreadReplyInput("source-1", "Processing complete."), tmp_path / "cache"
+    )
+    assert result.status == dex.FlowStatus.COMPLETED
+    assert result.single_output(ThreadReplyOutput) == ThreadReplyOutput("thread-1", "reply-1")
+    assert requests == ["full", "full", "metadata", "POST"]
+
+
+@pytest.mark.asyncio
+async def test_real_dex_unwired_optional_branch_fails_with_failure(tmp_path: Path) -> None:
+    """A definite Gmail 404 selects notFound and fails the unwired optional route."""
+    result = await _provider_flow(
+        lambda _: httpx.Response(404),
+        ThreadReplyInput("missing-1", "Processing complete."),
+        tmp_path / "cache",
+    )
+    assert result.status == dex.FlowStatus.FAILED
+    assert result.error_message is not None
+    assert "notFound" in result.error_message
+
+
+@pytest.mark.asyncio
+async def test_real_dex_manifest_mocks_run_the_same_flow(tmp_path: Path) -> None:
+    """Manifest default Query and Mutation cases complete through the two Step factories."""
+    mock = Mock(CONNECTION_NAME)
+    result = await _run_flow(
+        mock.connection, ThreadReplyInput("source-1", "Processing complete."), tmp_path / "cache"
+    )
+    assert result.status == dex.FlowStatus.COMPLETED
+    assert result.single_output(ThreadReplyOutput) == ThreadReplyOutput(
+        "18c0a1b2c3d4e5f0", "18c0a1b2c3d4e700"
+    )
+    assert len(mock.get_message.calls()) == 1
+    assert len(mock.reply_to_message.calls()) == 1
+
+
+# dex:group group-id:gmail group-label:"Gmail"
+# dex:explanation text:"Complete after Gmail confirms one new message was sent."
+class SendConfirmed(dex.Step[MutationResult[SendMessageOutput]]):
+    """Complete after the connector proves a send was accepted."""
+
+    async def execute(  # type: ignore[override]
+        self, context: dex.AsyncContext, input: MutationResult[SendMessageOutput]
+    ) -> dex.StepDecision:
+        """Return only Gmail's message ID."""
+        return dex.graceful_complete(input.value.message_id)
+
+
+class SendMessageFlow(dex.Flow[SendMessageInput]):
+    """Exercise the third Gmail operation-specific Step factory on real Dex."""
+
+    def __init__(self, connection: Connection) -> None:
+        self.confirmed = SendConfirmed()
+        self.send = new_send_message_step(
+            step_type="SendOneEmail",
+            step_input_type=SendMessageInput,
+            annotations=StepAnnotations(
+                group_id="gmail", group_label="Gmail", explanation="Send one message after read-back."
+            ),
+            connection=connection,
+            connection_name=CONNECTION_NAME,
+            map_to_operation_input=lambda value: value,
+            sent=self.confirmed,
+        )
+
+    def get_steps(self) -> dex.StepList[SendMessageInput]:
+        """Register sendMessage and its happy-path completion target."""
+        return dex.StepList.start_step(self.send).other_steps(self.confirmed)
+
+
+@pytest.mark.asyncio
+async def test_real_dex_send_retry_reads_back_before_duplicate_post(tmp_path: Path) -> None:
+    """An ambiguous first POST retries, then finds the sent message before another POST."""
+    methods: list[str] = []
+
+    def respond(request: httpx.Request) -> httpx.Response:
+        methods.append(request.method)
+        if request.method == "POST":
+            return httpx.Response(500)
+        if methods.count("GET") <= 4:
+            return httpx.Response(200, json={"messages": []})
+        return httpx.Response(200, json={"messages": [{"id": "sent-1", "threadId": "thread-1"}]})
+
+    credential = Credentials(SecretString("inert-access"), "owner@example.org")
+    credentials = StaticCredentialProvider({ConnectionRef("google", CONNECTION_NAME): credential})
+    async with httpx.AsyncClient(transport=httpx.MockTransport(respond)) as http_client:
+        provider = GmailProvider(
+            Config(endpoint="http://localhost/gmail/v1"), credentials, http_client=http_client
+        )
+        flow = SendMessageFlow(new_connection(provider, ConnectionRef("google", CONNECTION_NAME)))
+        assert flow.send.get_step_options().execute_durability == dex.StepDurability.ASYNC
+        result = await _run_registered_flow(
+            flow,
+            SendMessageInput(["ada@example.com"], "Progress", "Processing complete."),
+            tmp_path / "cache",
+        )
+    assert result.status == dex.FlowStatus.COMPLETED, (result.error_message, methods)
+    assert result.single_output(str) == "sent-1"
+    assert methods == ["POST", "GET", "GET", "GET", "GET", "GET"]
+
+
+@pytest.mark.asyncio
+async def test_real_dex_503_resends_after_sent_mail_miss(tmp_path: Path) -> None:
+    """A definite 503 retries with one pre-send search before the second POST."""
+    methods: list[str] = []
+
+    def respond(request: httpx.Request) -> httpx.Response:
+        methods.append(request.method)
+        if request.method == "GET":
+            return httpx.Response(200, json={"messages": []})
+        if methods.count("POST") == 1:
+            return httpx.Response(503)
+        return httpx.Response(200, json={"id": "sent-after-503", "threadId": "thread-1"})
+
+    credential = Credentials(SecretString("inert-access"), "owner@example.org")
+    credentials = StaticCredentialProvider({ConnectionRef("google", CONNECTION_NAME): credential})
+    async with httpx.AsyncClient(transport=httpx.MockTransport(respond)) as http_client:
+        provider = GmailProvider(
+            Config(endpoint="http://localhost/gmail/v1"), credentials, http_client=http_client
+        )
+        flow = SendMessageFlow(new_connection(provider, ConnectionRef("google", CONNECTION_NAME)))
+        assert flow.send.get_step_options().execute_durability == dex.StepDurability.ASYNC
+        result = await _run_registered_flow(
+            flow,
+            SendMessageInput(["ada@example.com"], "Progress", "Processing complete."),
+            tmp_path / "cache",
+        )
+    assert result.status == dex.FlowStatus.COMPLETED, (result.error_message, methods)
+    assert result.single_output(str) == "sent-after-503"
+    assert methods == ["POST", "GET", "GET", "GET", "GET", "GET", "POST"]

dex_connector_google_gmail-0.1.0/examples/thread_reply/worker.py

@@ -0,0 +1,24 @@
+# Copyright (c) 2026 Super Durable
+# SPDX-License-Identifier: MIT
+"""Run the Gmail example Flow with the released async Dex Worker."""
+
+from dex import AsyncWorker, BlobCacheConfig, Flow, Registry, WorkerOptions, open_blob_cache
+
+from .models import ThreadReplyInput
+
+
+async def run_thread_reply_worker(
+    flow: Flow[ThreadReplyInput], cache_directory: str, server_address: str = "localhost:8801"
+) -> None:
+    """Register one Flow on a pull Worker and close its local blob cache on exit."""
+    if flow is None or not cache_directory:
+        raise ValueError("thread reply Flow and blob cache directory are required")
+    blob_cache = open_blob_cache(BlobCacheConfig(cache_directory, 64 * 1024 * 1024))
+    worker = AsyncWorker(
+        Registry([flow], allow_async_handlers=True), blob_cache, WorkerOptions(server_address=server_address)
+    )
+    try:
+        await worker.start()
+    finally:
+        await worker.close()
+        blob_cache.close()