adloop 0.18.1__tar.gz → 0.19.1__tar.gz

{adloop-0.18.1 → adloop-0.19.1}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.3
 Name: adloop
-Version: 0.18.1
+Version: 0.19.1
 Summary: The AI command center for Google Ads, Reddit Ads, GA4, and tracking code.
 Keywords: mcp,google-ads,reddit-ads,google-analytics,ga4,cursor,marketing
 Author: Daniel Klose
 Author-email: Daniel Klose <info@daniel-klose.com>
 License: MIT
-Requires-Dist: fastmcp>=3.0.0
+Requires-Dist: fastmcp>=4.0
 Requires-Dist: google-ads>=32.0.0
 Requires-Dist: google-analytics-data>=0.20.0
 Requires-Dist: google-analytics-admin>=0.27.0
@@ -254,8 +254,8 @@ All write operations follow a **draft → preview → confirm** workflow. Nothin
 | `draft_responsive_search_ad` | Create RSA preview (3-15 headlines ≤30 chars, 2-4 descriptions ≤90 chars). Warns if headline/description count is below best practice. |
 | `draft_callouts` | Create campaign callout assets from 1-25 character text snippets. |
 | `draft_structured_snippets` | Create campaign structured snippet assets using official header values and 3-10 snippet values. |
-| `draft_image_assets` | Create campaign image assets from local PNG, JPEG, or GIF files. |
-| `draft_keywords` | Propose keyword additions with match types. Proactively checks bidding strategy — blocks BROAD match on Manual CPC campaigns. |
+| `draft_image_assets` | Create campaign image assets from local files or public image URLs (PNG, JPEG, or GIF). |
+| `draft_keywords` | Propose keyword additions with match types. Proactively checks bidding strategy — flags BROAD match on campaigns without Smart Bidding as dangerous in the preview. |
 | `add_negative_keywords` | Propose negative keywords directly on a campaign |
 | `add_negative_locations` | Propose negative geo exclusions on a campaign — exclude cities/regions while keeping broader positive targets |
 | `draft_key_event` | Mark a GA4 event as a key event (conversion) — the fix for "fires but isn't tracked as a conversion" |
@@ -314,8 +314,8 @@ AdLoop manages real ad spend, so safety is not optional.
 - **Budget caps.** Configurable maximum daily budget — the server rejects anything above the cap.
 - **Audit log.** Every operation (including dry runs) is logged to `~/.adloop/audit.log`.
 - **New campaigns and ads are PAUSED.** Nothing goes live without manual enablement.
-- **Destructive ops require double confirmation.** Removing entities or large budget increases trigger extra warnings.
-- **Broad Match + Manual CPC blocked.** The #1 cause of wasted ad spend is automatically prevented — `draft_keywords` refuses to add BROAD match keywords to campaigns without Smart Bidding.
+- **Destructive ops are flagged for double confirmation.** Removing entities or large budget increases come back with extra warnings, and the AI is instructed to confirm twice.
+- **Broad Match without Smart Bidding caught.** The #1 cause of wasted ad spend: `draft_campaign` refuses BROAD keywords unless the campaign uses Smart Bidding, and `draft_keywords` / `draft_ad_group` mark them as dangerous in the preview, so the AI has to raise it before anything is applied.
 - **Pre-write validation.** Before any write, the AI checks bidding strategy, conversion tracking status, and quality scores. If the campaign is fundamentally broken, AdLoop warns you instead of making things worse.
 - **Structured error handling.** All tools return actionable error messages with hints instead of raw exceptions. Auth errors include specific re-authorization steps.
 - **API version pinning.** The Google Ads API version is pinned to prevent silent breaking changes from library updates. `health_check` warns when a newer version is available.
@@ -578,7 +578,7 @@ What's been shipped and what's next:
 - ~~PyPI package~~ ✓ — `pip install adloop`
 - ~~[AdLoop Cloud](https://getadloop.com)~~ ✓ — the hosted version: no Google Cloud project, no API access application, connect Google in two clicks (EU-hosted, GDPR-first)
 - ~~Headless server support~~ ✓ — manual URL copy-paste flow for servers without a browser
-- ~~Behavioral eval suites~~ ✓ — 28 prompt-and-expectation tests covering read, write, tracking, and planning workflows
+- ~~Behavioral eval suites~~ ✓ — prompt-and-expectation tests in `tests/evals/` covering read, write, tracking, and planning workflows
 - ~~Google Tag Manager integration~~ ✓ — read tools for tags, triggers, variables, workspaces, and version history, plus the `audit_event_coverage` three-way join across codebase events, GTM tags, and GA4 actual fires
 - **Community launch** — HN, Indie Hackers, r/cursor, Twitter
 - **Video walkthrough**

{adloop-0.18.1 → adloop-0.19.1}/README.md

@@ -227,8 +227,8 @@ All write operations follow a **draft → preview → confirm** workflow. Nothin
 | `draft_responsive_search_ad` | Create RSA preview (3-15 headlines ≤30 chars, 2-4 descriptions ≤90 chars). Warns if headline/description count is below best practice. |
 | `draft_callouts` | Create campaign callout assets from 1-25 character text snippets. |
 | `draft_structured_snippets` | Create campaign structured snippet assets using official header values and 3-10 snippet values. |
-| `draft_image_assets` | Create campaign image assets from local PNG, JPEG, or GIF files. |
-| `draft_keywords` | Propose keyword additions with match types. Proactively checks bidding strategy — blocks BROAD match on Manual CPC campaigns. |
+| `draft_image_assets` | Create campaign image assets from local files or public image URLs (PNG, JPEG, or GIF). |
+| `draft_keywords` | Propose keyword additions with match types. Proactively checks bidding strategy — flags BROAD match on campaigns without Smart Bidding as dangerous in the preview. |
 | `add_negative_keywords` | Propose negative keywords directly on a campaign |
 | `add_negative_locations` | Propose negative geo exclusions on a campaign — exclude cities/regions while keeping broader positive targets |
 | `draft_key_event` | Mark a GA4 event as a key event (conversion) — the fix for "fires but isn't tracked as a conversion" |
@@ -287,8 +287,8 @@ AdLoop manages real ad spend, so safety is not optional.
 - **Budget caps.** Configurable maximum daily budget — the server rejects anything above the cap.
 - **Audit log.** Every operation (including dry runs) is logged to `~/.adloop/audit.log`.
 - **New campaigns and ads are PAUSED.** Nothing goes live without manual enablement.
-- **Destructive ops require double confirmation.** Removing entities or large budget increases trigger extra warnings.
-- **Broad Match + Manual CPC blocked.** The #1 cause of wasted ad spend is automatically prevented — `draft_keywords` refuses to add BROAD match keywords to campaigns without Smart Bidding.
+- **Destructive ops are flagged for double confirmation.** Removing entities or large budget increases come back with extra warnings, and the AI is instructed to confirm twice.
+- **Broad Match without Smart Bidding caught.** The #1 cause of wasted ad spend: `draft_campaign` refuses BROAD keywords unless the campaign uses Smart Bidding, and `draft_keywords` / `draft_ad_group` mark them as dangerous in the preview, so the AI has to raise it before anything is applied.
 - **Pre-write validation.** Before any write, the AI checks bidding strategy, conversion tracking status, and quality scores. If the campaign is fundamentally broken, AdLoop warns you instead of making things worse.
 - **Structured error handling.** All tools return actionable error messages with hints instead of raw exceptions. Auth errors include specific re-authorization steps.
 - **API version pinning.** The Google Ads API version is pinned to prevent silent breaking changes from library updates. `health_check` warns when a newer version is available.
@@ -551,7 +551,7 @@ What's been shipped and what's next:
 - ~~PyPI package~~ ✓ — `pip install adloop`
 - ~~[AdLoop Cloud](https://getadloop.com)~~ ✓ — the hosted version: no Google Cloud project, no API access application, connect Google in two clicks (EU-hosted, GDPR-first)
 - ~~Headless server support~~ ✓ — manual URL copy-paste flow for servers without a browser
-- ~~Behavioral eval suites~~ ✓ — 28 prompt-and-expectation tests covering read, write, tracking, and planning workflows
+- ~~Behavioral eval suites~~ ✓ — prompt-and-expectation tests in `tests/evals/` covering read, write, tracking, and planning workflows
 - ~~Google Tag Manager integration~~ ✓ — read tools for tags, triggers, variables, workspaces, and version history, plus the `audit_event_coverage` three-way join across codebase events, GTM tags, and GA4 actual fires
 - **Community launch** — HN, Indie Hackers, r/cursor, Twitter
 - **Video walkthrough**

{adloop-0.18.1 → adloop-0.19.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "adloop"
-version = "0.18.1"
+version = "0.19.1"
 description = "The AI command center for Google Ads, Reddit Ads, GA4, and tracking code."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -14,7 +14,7 @@ keywords = [
     "marketing",
 ]
 dependencies = [
-    "fastmcp>=3.0.0",
+    "fastmcp>=4.0",
     "google-ads>=32.0.0",
     "google-analytics-data>=0.20.0",
     "google-analytics-admin>=0.27.0",

{adloop-0.18.1 → adloop-0.19.1}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "adloop"
-version = "0.18.1"
+version = "0.19.1"
 description = "The AI command center for Google Ads, Reddit Ads, GA4, and tracking code."
 readme = "README.md"
 authors = [
@@ -10,7 +10,7 @@ requires-python = ">=3.11"
 license = { text = "MIT" }
 keywords = ["mcp", "google-ads", "reddit-ads", "google-analytics", "ga4", "cursor", "marketing"]
 dependencies = [
-    "fastmcp>=3.0.0",
+    "fastmcp>=4.0",
     "google-ads>=32.0.0",
     "google-analytics-data>=0.20.0",
     "google-analytics-admin>=0.27.0",

{adloop-0.18.1 → adloop-0.19.1}/src/adloop/_mcp_patches.py

@@ -71,7 +71,13 @@ def _patch_request_responder_cancel_race() -> None:
     """
     try:
         from mcp.shared import session as _session_module
-    except Exception as exc:  # pragma: no cover — mcp is a hard dep
+    except ModuleNotFoundError:
+        # mcp 2 rewrote the session layer: the racing RequestResponder is gone
+        # and the new dispatcher has a single response writer, so there is
+        # nothing to patch. Not an error.
+        _log("pysdk-2416 not applicable: mcp>=2 has no RequestResponder race")
+        return
+    except Exception as exc:  # pragma: no cover — unexpected import failure
         _log(f"skip pysdk-2416: cannot import mcp.shared.session ({exc})")
         return
 

{adloop-0.18.1 → adloop-0.19.1}/src/adloop/ads/custom_conversion_goals.py

@@ -537,7 +537,6 @@ def draft_clear_custom_conversion_goal(
 
     Call ``confirm_and_apply`` with the returned plan_id to execute.
     """
-    from adloop.ads.client import normalize_customer_id
     from adloop.safety.guards import SafetyViolation, check_blocked_operation
     from adloop.safety.preview import ChangePlan, store_plan
 
@@ -553,7 +552,6 @@ def draft_clear_custom_conversion_goal(
             "details": ["campaign_id must be a numeric ID"],
         }
 
-    cid = normalize_customer_id(customer_id or config.ads.customer_id)
     state = _custom_goal_state(config, customer_id, campaign_id=campaign_id)
     campaign = find_campaign(state, campaign_id)
     if campaign is None:

adloop-0.19.1/src/adloop/ads/image_fetch.py

@@ -0,0 +1,331 @@
+"""Fetch ad images from public URLs without letting the fetch reach private hosts.
+
+The fetched bytes are uploaded into the user's Google Ads account, where
+they become visible. A fetch that could be steered at an internal address
+(cloud metadata, a database admin page, a loopback service) would therefore
+be a way to exfiltrate whatever lives there. So, unlike the up/down
+reachability check for landing pages, this fetcher closes the DNS-rebinding
+gap:
+
+* the hostname is resolved exactly once per request, and every resolved
+  address must be public;
+* the TCP connection goes to that resolved address (pinning) — the socket
+  never resolves the name again — while the request still carries the
+  original ``Host`` header and, for https, TLS uses the original hostname
+  for SNI and certificate verification;
+* redirects are followed by hand (at most ``MAX_REDIRECTS``), each hop
+  re-validated and re-pinned;
+* the body is streamed under a hard size cap and a wall-clock deadline;
+* the content is trusted only after sniffing the bytes, never by
+  ``Content-Type``.
+
+No cookies, credentials or auth headers are ever sent.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import http.client
+import ipaddress
+import socket
+import ssl
+import time
+from dataclasses import dataclass
+from urllib.parse import urljoin, urlsplit
+
+# Google Ads rejects image assets above 5120 KB.
+MAX_IMAGE_BYTES = 5120 * 1024
+MAX_REDIRECTS = 3
+TIMEOUT_SECONDS = 10.0
+
+_REDIRECT_STATUSES = frozenset({301, 302, 303, 307, 308})
+_CHUNK_SIZE = 64 * 1024
+_NAT64_PREFIX = ipaddress.ip_network("64:ff9b::/96")
+
+
+class ImageFetchError(ValueError):
+    """The image URL could not be fetched safely or is not a usable image."""
+
+
+@dataclass(frozen=True)
+class FetchedImage:
+    """Bytes fetched from ``url`` (after following ``final_url`` redirects)."""
+
+    url: str
+    final_url: str
+    data: bytes
+
+    @property
+    def sha256(self) -> str:
+        return hashlib.sha256(self.data).hexdigest()
+
+
+def non_public_reason(
+    addr: ipaddress.IPv4Address | ipaddress.IPv6Address,
+) -> str | None:
+    """Return why ``addr`` must not be fetched from, or None if it is public.
+
+    IPv6 forms that embed an IPv4 address (IPv4-mapped, 6to4, Teredo,
+    NAT64) are judged by the embedded address too, so ``::ffff:127.0.0.1``
+    cannot slip past as "an IPv6 address that isn't loopback".
+    """
+    if isinstance(addr, ipaddress.IPv6Address):
+        if addr.ipv4_mapped is not None:
+            # The socket really talks IPv4 to the mapped address, so that
+            # address alone decides.
+            inner_reason = non_public_reason(addr.ipv4_mapped)
+            if inner_reason is not None:
+                return f"maps to {addr.ipv4_mapped}, {inner_reason}"
+            return None
+        embedded = [addr.sixtofour, *(addr.teredo or ())]
+        if addr in _NAT64_PREFIX:
+            embedded.append(ipaddress.IPv4Address(int(addr) & 0xFFFFFFFF))
+        for inner in embedded:
+            if inner is not None and non_public_reason(inner) is not None:
+                return f"embeds non-public address {inner}"
+
+    for label in (
+        "unspecified",
+        "loopback",
+        "link_local",
+        "multicast",
+        "private",
+        "reserved",
+    ):
+        if getattr(addr, f"is_{label}"):
+            return label.replace("_", "-")
+    if not addr.is_global:
+        return "not globally routable"
+    return None
+
+
+def resolve_public_address(host: str, port: int) -> str:
+    """Resolve ``host`` once and return the address to connect to.
+
+    Raises ImageFetchError when the name does not resolve or when ANY of
+    its addresses is non-public — a hostname that mixes public and private
+    records is refused outright rather than having one picked.
+    """
+    try:
+        literal = ipaddress.ip_address(host)
+    except ValueError:
+        literal = None
+
+    if literal is not None:
+        addresses = [literal]
+    else:
+        try:
+            infos = socket.getaddrinfo(
+                host, port, type=socket.SOCK_STREAM, proto=socket.IPPROTO_TCP
+            )
+        except (OSError, UnicodeError) as exc:
+            raise ImageFetchError(f"hostname {host!r} does not resolve: {exc}") from exc
+        addresses = []
+        for info in infos:
+            try:
+                addresses.append(ipaddress.ip_address(info[4][0]))
+            except ValueError as exc:
+                raise ImageFetchError(
+                    f"hostname {host!r} resolved to an unusable address {info[4][0]!r}"
+                ) from exc
+        if not addresses:
+            raise ImageFetchError(f"hostname {host!r} has no addresses")
+
+    for addr in addresses:
+        reason = non_public_reason(addr)
+        if reason is not None:
+            raise ImageFetchError(
+                f"{host} resolves to a non-public address ({addr}, {reason}) — "
+                "refusing to fetch"
+            )
+    return str(addresses[0])
+
+
+class _PinnedHTTPConnection(http.client.HTTPConnection):
+    """HTTP connection that dials a pre-resolved IP instead of ``host``.
+
+    ``self.host`` stays the original hostname, so http.client still sends
+    the right ``Host`` header.
+    """
+
+    def __init__(self, host: str, port: int, *, pinned_ip: str, timeout: float) -> None:
+        super().__init__(host, port, timeout=timeout)
+        self.pinned_ip = pinned_ip
+
+    def connect(self) -> None:
+        self.sock = socket.create_connection((self.pinned_ip, self.port), self.timeout)
+
+
+class _PinnedHTTPSConnection(http.client.HTTPSConnection):
+    """HTTPS connection that dials a pre-resolved IP.
+
+    TLS still uses the original hostname for SNI and certificate
+    verification, so pinning cannot be abused to accept a certificate for
+    a different name.
+    """
+
+    def __init__(
+        self,
+        host: str,
+        port: int,
+        *,
+        pinned_ip: str,
+        timeout: float,
+        context: ssl.SSLContext,
+    ) -> None:
+        super().__init__(host, port, timeout=timeout, context=context)
+        self.pinned_ip = pinned_ip
+        self.tls_context = context
+
+    def connect(self) -> None:
+        raw = socket.create_connection((self.pinned_ip, self.port), self.timeout)
+        try:
+            self.sock = self.tls_context.wrap_socket(raw, server_hostname=self.host)
+        except BaseException:
+            raw.close()
+            raise
+
+
+def _tls_context() -> ssl.SSLContext:
+    """Default verifying context: CERT_REQUIRED + hostname checking."""
+    return ssl.create_default_context()
+
+
+def _user_agent() -> str:
+    from adloop import __version__
+
+    return f"AdLoop/{__version__} (image asset fetch)"
+
+
+@dataclass(frozen=True)
+class _Target:
+    scheme: str
+    host: str
+    port: int
+    path: str
+
+
+def _parse_target(url: str) -> _Target:
+    try:
+        parts = urlsplit(url)
+        port = parts.port
+    except ValueError as exc:
+        raise ImageFetchError(f"unparseable URL {url!r}: {exc}") from exc
+
+    scheme = parts.scheme.lower()
+    if scheme not in ("http", "https"):
+        raise ImageFetchError(
+            f"unsupported URL scheme {parts.scheme!r} in {url!r} (only http/https)"
+        )
+    if parts.username is not None or parts.password is not None:
+        raise ImageFetchError(f"URL {url!r} contains credentials — refusing to fetch")
+    host = parts.hostname
+    if not host:
+        raise ImageFetchError(f"URL {url!r} has no hostname")
+    try:
+        ipaddress.ip_address(host)
+    except ValueError:
+        try:
+            host = host.encode("idna").decode("ascii")
+        except UnicodeError as exc:
+            raise ImageFetchError(f"invalid hostname in {url!r}: {exc}") from exc
+
+    path = parts.path or "/"
+    if parts.query:
+        path = f"{path}?{parts.query}"
+    return _Target(
+        scheme=scheme,
+        host=host,
+        port=port or (443 if scheme == "https" else 80),
+        path=path,
+    )
+
+
+def _open_connection(target: _Target, pinned_ip: str) -> http.client.HTTPConnection:
+    if target.scheme == "https":
+        return _PinnedHTTPSConnection(
+            target.host,
+            target.port,
+            pinned_ip=pinned_ip,
+            timeout=TIMEOUT_SECONDS,
+            context=_tls_context(),
+        )
+    return _PinnedHTTPConnection(
+        target.host, target.port, pinned_ip=pinned_ip, timeout=TIMEOUT_SECONDS
+    )
+
+
+def _read_capped(response: http.client.HTTPResponse, url: str, deadline: float) -> bytes:
+    """Stream the body, aborting the moment it exceeds the size cap."""
+    declared = response.getheader("Content-Length")
+    if declared is not None and declared.strip().isdigit():
+        if int(declared) > MAX_IMAGE_BYTES:
+            raise ImageFetchError(
+                f"image at {url} is {int(declared) // 1024} KB; Google Ads "
+                f"accepts at most {MAX_IMAGE_BYTES // 1024} KB"
+            )
+
+    read = getattr(response, "read1", None) or response.read
+    chunks: list[bytes] = []
+    total = 0
+    while True:
+        if time.monotonic() > deadline:
+            raise ImageFetchError(
+                f"fetching {url} took longer than {TIMEOUT_SECONDS:.0f}s"
+            )
+        # read1 returns whatever has arrived instead of waiting for a full
+        # chunk, so a server trickling a byte at a time cannot outlast the
+        # deadline: the per-recv socket timeout alone would never fire.
+        chunk = read(_CHUNK_SIZE)
+        if not chunk:
+            break
+        total += len(chunk)
+        if total > MAX_IMAGE_BYTES:
+            raise ImageFetchError(
+                f"image at {url} exceeds {MAX_IMAGE_BYTES // 1024} KB, the "
+                "Google Ads image asset limit"
+            )
+        chunks.append(chunk)
+    return b"".join(chunks)
+
+
+def fetch_image_bytes(url: str) -> FetchedImage:
+    """Fetch ``url`` safely and return the raw bytes (not yet sniffed)."""
+    current = url
+    for _hop in range(MAX_REDIRECTS + 1):
+        target = _parse_target(current)
+        pinned_ip = resolve_public_address(target.host, target.port)
+        deadline = time.monotonic() + TIMEOUT_SECONDS
+        connection = _open_connection(target, pinned_ip)
+        try:
+            connection.request(
+                "GET",
+                target.path,
+                headers={
+                    "User-Agent": _user_agent(),
+                    "Accept": "image/png, image/jpeg, image/gif",
+                    "Accept-Encoding": "identity",
+                    "Connection": "close",
+                },
+            )
+            response = connection.getresponse()
+            if response.status in _REDIRECT_STATUSES:
+                location = response.getheader("Location")
+                if not location:
+                    raise ImageFetchError(
+                        f"{current} answered HTTP {response.status} without a Location"
+                    )
+                current = urljoin(current, location.strip())
+                continue
+            if response.status != 200:
+                raise ImageFetchError(f"{current} answered HTTP {response.status}")
+            data = _read_capped(response, current, deadline)
+        except ImageFetchError:
+            raise
+        except (OSError, http.client.HTTPException) as exc:
+            raise ImageFetchError(f"could not fetch {current}: {exc}") from exc
+        finally:
+            connection.close()
+        return FetchedImage(url=url, final_url=current, data=data)
+
+    raise ImageFetchError(f"{url} redirected more than {MAX_REDIRECTS} times")

{adloop-0.18.1 → adloop-0.19.1}/src/adloop/ads/read.py

@@ -373,7 +373,11 @@ def get_search_terms(
     """Get search terms report — what users actually typed before clicking ads."""
     from adloop.ads.gaql import execute_query
 
-    date_clause = _date_clause(date_range_start, date_range_end)
+    # search_term_view requires an explicit date segment, so the default is
+    # DURING LAST_30_DAYS and a given range replaces it. ``_date_clause``
+    # prefixes its fragment with AND (the other read tools append it to a
+    # WHERE); here it is the only predicate, so the AND comes off.
+    where = _date_clause(date_range_start, date_range_end).removeprefix("AND ")
 
     query = f"""
         SELECT search_term_view.search_term,
@@ -381,35 +385,10 @@ def get_search_terms(
                metrics.impressions, metrics.clicks,
                metrics.cost_micros, metrics.conversions
         FROM search_term_view
-        WHERE segments.date DURING LAST_30_DAYS
-          {f"AND segments.date BETWEEN '{date_range_start}' AND '{date_range_end}'" if date_range_start and date_range_end else ""}
+        WHERE {where}
         ORDER BY metrics.clicks DESC
         LIMIT 200
     """
-    # search_term_view requires an explicit date segment, so we always
-    # include DURING LAST_30_DAYS as baseline and override if dates given.
-    if date_range_start and date_range_end:
-        query = f"""
-            SELECT search_term_view.search_term,
-                   campaign.name, ad_group.name,
-                   metrics.impressions, metrics.clicks,
-                   metrics.cost_micros, metrics.conversions
-            FROM search_term_view
-            WHERE segments.date BETWEEN '{date_range_start}' AND '{date_range_end}'
-            ORDER BY metrics.clicks DESC
-            LIMIT 200
-        """
-    else:
-        query = """
-            SELECT search_term_view.search_term,
-                   campaign.name, ad_group.name,
-                   metrics.impressions, metrics.clicks,
-                   metrics.cost_micros, metrics.conversions
-            FROM search_term_view
-            WHERE segments.date DURING LAST_30_DAYS
-            ORDER BY metrics.clicks DESC
-            LIMIT 200
-        """
 
     rows = execute_query(config, customer_id, query)
     currency_code = get_currency_code(config, customer_id)

{adloop-0.18.1 → adloop-0.19.1}/src/adloop/ads/write.py

@@ -8,7 +8,7 @@ from __future__ import annotations
 
 import hashlib
 import struct
-from pathlib import Path
+from pathlib import Path, PurePath, PurePosixPath
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
@@ -209,7 +209,9 @@ def _ssrf_error(url: str) -> str | None:
     Note: the fetch re-resolves DNS after this check, so a hostile DNS
     server could still rebind between check and fetch — acceptable here
     because the fetch result is only an up/down signal, never returned
-    to the caller.
+    to the caller. Fetches whose bytes ARE used (image assets) go through
+    ``adloop.ads.image_fetch``, which pins the connection to the checked
+    address.
     """
     import ipaddress
     import socket
@@ -238,15 +240,10 @@ def _ssrf_error(url: str) -> str | None:
             ipaddress.ip_address(info[4][0]) for info in addr_info
         ]
 
+    from adloop.ads.image_fetch import non_public_reason
+
     for addr in addresses:
-        if (
-            addr.is_private
-            or addr.is_loopback
-            or addr.is_link_local
-            or addr.is_multicast
-            or addr.is_reserved
-            or addr.is_unspecified
-        ):
+        if non_public_reason(addr) is not None:
             return (
                 f"URL resolves to a non-public address ({addr}) — "
                 "refusing to fetch"
@@ -383,10 +380,67 @@ def _parse_image_metadata(path_str: str) -> dict[str, object]:
         "mime_type": mime_type,
         "width": width,
         "height": height,
+        "size_kb": _size_kb(data),
     }
 
 
-def _build_image_asset_name(path: Path, data: bytes) -> str:
+def _parse_image_url_metadata(url: str) -> dict[str, object]:
+    """Fetch an image URL safely and return metadata used for asset creation.
+
+    The bytes themselves are NOT returned: plans are persisted, so only a
+    sha256 of the approved bytes is kept. Apply re-fetches the URL and
+    refuses if the digest no longer matches.
+    """
+    from adloop.ads.image_fetch import fetch_image_bytes
+
+    fetched = fetch_image_bytes(url)
+    mime_type, width, height = _detect_image_type_and_size(fetched.data)
+    return {
+        "url": url,
+        "sha256": fetched.sha256,
+        "name": _build_image_asset_name(_url_path(url), fetched.data),
+        "mime_type": mime_type,
+        "width": width,
+        "height": height,
+        "size_kb": _size_kb(fetched.data),
+    }
+
+
+def _fetch_approved_image_url(payload: dict) -> bytes:
+    """Re-fetch a URL image at apply time and check it is the previewed one."""
+    from adloop.ads.image_fetch import fetch_image_bytes
+
+    url = str(payload["url"])
+    fetched = fetch_image_bytes(url)
+    if fetched.sha256 != payload.get("sha256"):
+        raise ValueError(
+            f"The image at {url} changed since the preview; draft again."
+        )
+    return fetched.data
+
+
+def _url_path(url: str) -> PurePosixPath:
+    """The URL's path, so asset names use its file stem like local images do."""
+    from urllib.parse import unquote, urlsplit
+
+    return PurePosixPath(unquote(urlsplit(url).path))
+
+
+def _size_kb(data: bytes) -> float:
+    return round(len(data) / 1024, 1)
+
+
+def _describe_image(image: dict[str, object]) -> str:
+    """One preview line: source, type, dimensions and size."""
+    source = image.get("url") or image.get("path")
+    kind = str(image.get("mime_type", "")).removeprefix("image/").upper()
+    return (
+        f"{source} — {kind} {image.get('width')}x{image.get('height')}, "
+        f"{image.get('size_kb')} KB"
+    )
+
+
+def _build_image_asset_name(path: PurePath, data: bytes) -> str:
     """Build a deterministic asset name required by Google Ads image assets."""
     digest = hashlib.sha1(data).hexdigest()[:12]
     stem = path.stem.strip() or "image"
@@ -394,7 +448,7 @@ def _build_image_asset_name(path: Path, data: bytes) -> str:
 
 
 def _detect_image_type_and_size(data: bytes) -> tuple[str, int, int]:
-    """Return MIME type plus width/height for supported local image files."""
+    """Return MIME type plus width/height, sniffed from the bytes alone."""
     if data.startswith(b"\x89PNG\r\n\x1a\n") and len(data) >= 24:
         width, height = struct.unpack(">II", data[16:24])
         return "image/png", width, height
@@ -439,7 +493,7 @@ def _detect_image_type_and_size(data: bytes) -> tuple[str, int, int]:
             index += segment_length
 
     raise ValueError(
-        "Unsupported image type. Use a local PNG, JPEG, or GIF file."
+        "Unsupported image type. Use a PNG, JPEG, or GIF image."
     )
 
 
@@ -2402,18 +2456,27 @@ def draft_image_assets(
     customer_id: str = "",
     campaign_id: str = "",
     image_paths: list[str] | None = None,
+    image_urls: list[str] | None = None,
 ) -> dict:
-    """Draft campaign image assets from local files."""
+    """Draft campaign image assets from local files and/or public image URLs.
+
+    URL images are fetched now (public addresses only, pinned against DNS
+    rebinding, capped at Google's 5120 KB limit) and their sha256 is kept
+    in the plan; apply re-fetches and refuses if the bytes changed.
+    """
     from adloop.runtime import deployment_mode
     from adloop.safety.guards import SafetyViolation, check_blocked_operation
     from adloop.safety.preview import ChangePlan, store_plan
 
-    if deployment_mode() == "server":
+    image_paths = list(image_paths or [])
+    image_urls = list(image_urls or [])
+
+    if image_paths and deployment_mode() == "server":
         return {
             "error": (
-                "draft_image_assets reads image files from the local "
-                "filesystem and is not available on the hosted server. "
-                "Use the self-hosted AdLoop MCP server for image assets."
+                "image_paths can't be used here: local file paths aren't "
+                "available on a hosted server; pass image_urls (public "
+                "https/http links to PNG, JPEG or GIF images) instead."
             )
         }
 
@@ -2422,7 +2485,9 @@ def draft_image_assets(
     except SafetyViolation as e:
         return {"error": str(e)}
 
-    validated_images, errors = _validate_image_assets(campaign_id, image_paths or [])
+    validated_images, errors = _validate_image_assets(
+        campaign_id, image_paths, image_urls
+    )
     if errors:
         return {"error": "Validation failed", "details": errors}
 
@@ -2434,6 +2499,7 @@ def draft_image_assets(
         changes={
             "campaign_id": campaign_id,
             "images": validated_images,
+            "summary": [_describe_image(image) for image in validated_images],
         },
     )
     store_plan(plan)
@@ -3018,15 +3084,16 @@ def _validate_structured_snippets(
 
 
 def _validate_image_assets(
-    campaign_id: str, image_paths: list[str]
+    campaign_id: str, image_paths: list[str], image_urls: list[str] | None = None
 ) -> tuple[list[dict[str, object]], list[str]]:
     errors = []
     validated = []
+    image_urls = image_urls or []
 
     if not campaign_id:
         errors.append("campaign_id is required")
-    if not image_paths:
-        errors.append("At least one image path is required")
+    if not image_paths and not image_urls:
+        errors.append("At least one image (image_paths or image_urls) is required")
 
     for index, image_path in enumerate(image_paths):
         try:
@@ -3034,6 +3101,12 @@ def _validate_image_assets(
         except ValueError as exc:
             errors.append(f"Image {index + 1}: {exc}")
 
+    for index, image_url in enumerate(image_urls):
+        try:
+            validated.append(_parse_image_url_metadata(image_url))
+        except ValueError as exc:
+            errors.append(f"Image URL {index + 1} ({image_url}): {exc}")
+
     return validated, errors
 
 
@@ -3794,7 +3867,6 @@ def _apply_create_campaign(client: object, cid: str, changes: dict) -> dict:
     results = {}
     num_keywords = len(kw_list)
     num_geo = len(changes.get("geo_target_ids") or [])
-    num_lang = len(changes.get("language_ids") or [])
     for i, resp in enumerate(response.mutate_operation_responses):
         rn = _extract_resource_name(resp)
         if rn:
@@ -4576,13 +4648,30 @@ def _apply_create_structured_snippets(
 
 
 def _apply_create_image_assets(client: object, cid: str, changes: dict) -> dict:
-    """Create image assets from local files and link them to a campaign."""
+    """Create image assets from local files or URLs and link them to a campaign.
+
+    URL images are re-fetched through the same safe fetcher and must match
+    the sha256 approved in the preview.
+    """
+
+    from adloop.runtime import deployment_mode
 
     def populate(asset: object, payload: dict) -> None:
-        image_path = Path(str(payload["path"]))
-        image_bytes = image_path.read_bytes()
+        if payload.get("url"):
+            image_bytes = _fetch_approved_image_url(payload)
+            name_source = _url_path(str(payload["url"]))
+        elif deployment_mode() == "server":
+            # Drafts refuse paths on a server; never read server files even
+            # if a path-based plan reached apply some other way.
+            raise ValueError(
+                "local file paths aren't available on a hosted server; "
+                "pass image_urls"
+            )
+        else:
+            name_source = Path(str(payload["path"]))
+            image_bytes = name_source.read_bytes()
         mime_type_name = _VALID_IMAGE_MIME_TYPES[str(payload["mime_type"])]
-        asset.name = str(payload.get("name") or _build_image_asset_name(image_path, image_bytes))
+        asset.name = str(payload.get("name") or _build_image_asset_name(name_source, image_bytes))
         asset.type_ = client.enums.AssetTypeEnum.IMAGE
         asset.image_asset.data = image_bytes
         asset.image_asset.mime_type = getattr(client.enums.MimeTypeEnum, mime_type_name)

{adloop-0.18.1 → adloop-0.19.1}/src/adloop/rules/adloop.md

@@ -203,7 +203,7 @@ Reddit is a second ad platform with its own connection (own OAuth app, no develo
 | `draft_responsive_search_ad` | Create RSA preview (does NOT publish) | 3-15 headlines (≤30 chars), 2-4 descriptions (≤90 chars), final_url required, path1/path2 (≤15 chars each). Each headline/description may be a plain string (unpinned) or `{"text": "...", "pinned_field": "HEADLINE_1"}` (pinned). Valid pin slots: `HEADLINE_1/2/3`, `DESCRIPTION_1/2`. Google permits ≤2 headlines per slot, ≤1 description per slot. |
 | `draft_callouts` | Create callout assets for a campaign (does NOT publish) | `campaign_id`, `callouts` list with 1-25 chars each |
 | `draft_structured_snippets` | Create structured snippet assets for a campaign (does NOT publish) | `campaign_id`, `snippets` list of `{header, values}` with official header values and 3-10 values |
-| `draft_image_assets` | Create image assets for a campaign from local files (does NOT publish) | `campaign_id`, `image_paths` list of local PNG/JPEG/GIF files |
+| `draft_image_assets` | Create image assets for a campaign from local files or public image URLs (does NOT publish) | `campaign_id`, `image_paths` (local PNG/JPEG/GIF files; not on a hosted server) and/or `image_urls` (public http(s) image links, ≤5120 KB; re-checked at apply — if the image changed since the preview, draft again) |
 | `draft_sitelinks` | Create sitelink extensions for a campaign (does NOT publish) | `campaign_id`, `sitelinks` list of {link_text ≤25 chars, final_url, description1 ≤35 chars, description2 ≤35 chars} |
 | `draft_keywords` | Propose keyword additions (does NOT add) | Each keyword needs `text` and `match_type` (EXACT/PHRASE/BROAD) |
 | `add_negative_keywords` | Propose negative keywords directly on a campaign (does NOT add) | `campaign_id`, keyword list, `match_type` |

{adloop-0.18.1 → adloop-0.19.1}/src/adloop/server.py

@@ -13,9 +13,11 @@ from pydantic import BeforeValidator
 from adloop import diagnostics
 from adloop.runtime import current_config
 
-_READONLY = ToolAnnotations(readOnlyHint=True, destructiveHint=False)
-_WRITE = ToolAnnotations(readOnlyHint=False, destructiveHint=False)
-_DESTRUCTIVE = ToolAnnotations(readOnlyHint=False, destructiveHint=True)
+# openWorldHint: every tool talks to an external service (Google, Reddit,
+# a live web page), which directories such as ChatGPT's require to be said.
+_READONLY = ToolAnnotations(readOnlyHint=True, destructiveHint=False, openWorldHint=True)
+_WRITE = ToolAnnotations(readOnlyHint=False, destructiveHint=False, openWorldHint=True)
+_DESTRUCTIVE = ToolAnnotations(readOnlyHint=False, destructiveHint=True, openWorldHint=True)
 
 # Toolset taxonomy: every tool carries exactly one of these tags (or "core",
 # which survives every ADLOOP_TOOLSETS selection — health_check and
@@ -552,6 +554,8 @@ def run_ga4_report(
 
     Date formats: "today", "yesterday", "7daysAgo", "28daysAgo", "90daysAgo", or "YYYY-MM-DD".
     If property_id is empty, uses the default from config.
+    Queries the GA4 Data API. Dimensions and metrics:
+    https://developers.google.com/analytics/devguides/reporting/data/v1/api-schema
     """
     from adloop.ga4.reports import run_ga4_report as _impl
 
@@ -660,6 +664,8 @@ def run_gsc_report(
         [{"filters": [{"dimension": "query", "operator": "contains",
                        "expression": "analytics"}]}]
     limit: maximum rows to return (default 100, max 25000).
+    Queries the Search Console API:
+    https://developers.google.com/webmaster-tools/v1/searchanalytics/query
     """
     from adloop.gsc.reports import run_gsc_report as _impl
 
@@ -708,8 +714,9 @@ def analyze_page_speed(url: str, strategy: str = "mobile") -> dict:
 def list_merchant_accounts() -> dict:
     """List Google Merchant Center accounts the connected user can access.
 
-    Call first to discover merchant IDs for get_merchant_feed_health.
-    Distinguishes standalone accounts from aggregator (MCA) accounts.
+    Returns each account's numeric ID, name and whether it is a test
+    account. Call it to find the account_id for get_merchant_feed_health;
+    not needed when merchant.account_id is set in the config.
     """
     from adloop.merchant.read import list_merchant_accounts as _impl
 
@@ -899,9 +906,9 @@ def get_negative_keyword_lists(
 ) -> dict:
     """List all shared negative keyword lists (SharedSets) in the account.
 
-    Returns each list's ID, name, status, and keyword count. Always call
-    this before propose_negative_keyword_list to avoid creating duplicates —
-    a suitable list may already exist and just need attaching to a campaign.
+    Returns each list's ID, name, status, and keyword count. Useful before
+    propose_negative_keyword_list: a suitable list may already exist and
+    just need attaching to a campaign.
     """
     from adloop.ads.read import get_negative_keyword_lists as _impl
 
@@ -1543,7 +1550,8 @@ def run_gaql(
     """Execute an arbitrary GAQL (Google Ads Query Language) query.
 
     Use this for advanced queries not covered by the other tools.
-    See the GAQL reference in the AdLoop cursor rules for syntax help.
+    Queries the Google Ads API. GAQL syntax and fields:
+    https://developers.google.com/google-ads/api/docs/query/overview
 
     format: "table" (default, readable), "json" (structured), "csv" (exportable)
     """
@@ -2125,8 +2133,8 @@ def add_to_negative_keyword_list(
 
     Use this when a suitable list already exists and only needs more keywords
     (instead of propose_negative_keyword_list, which creates a new list).
-    Always call get_negative_keyword_lists first to find the right shared_set_id
-    and get_negative_keyword_list_keywords to avoid duplicating existing terms.
+    The shared_set_id comes from get_negative_keyword_lists;
+    get_negative_keyword_list_keywords shows the terms already in a list.
 
     shared_set_id: numeric ID from get_negative_keyword_lists (shared_set.id).
     keywords: list of keyword strings to append (duplicates in the input list
@@ -2458,10 +2466,25 @@ def draft_structured_snippets(
 @_safe
 def draft_image_assets(
     campaign_id: str,
-    image_paths: _StrList,
+    image_paths: _StrList = [],  # noqa: B006 — mutable default required for MCP JSON schema
+    image_urls: _StrList = [],  # noqa: B006
     customer_id: str = "",
 ) -> dict:
-    """Draft campaign image assets from local PNG, JPEG, or GIF files."""
+    """Draft campaign image assets from local files or public image URLs — returns a PREVIEW.
+
+    Pass at least one image in total across image_paths and image_urls.
+    Images must be PNG, JPEG or GIF and at most 5120 KB (Google's limit).
+    URL images are downloaded now and checked; applying re-downloads them
+    and refuses if the image changed since the preview.
+
+    Args:
+        campaign_id: Numeric ID of the campaign to attach the images to.
+        image_paths: Local PNG/JPEG/GIF file paths on the machine running
+            AdLoop. Not available on a hosted server — use image_urls there.
+        image_urls: Public http(s) URLs of PNG/JPEG/GIF images. Links to
+            private, local or internal addresses are refused.
+        customer_id: Ads account ID. Defaults to the configured account.
+    """
     from adloop.ads.write import draft_image_assets as _impl
 
     return _impl(
@@ -2469,6 +2492,7 @@ def draft_image_assets(
         customer_id=customer_id or current_config().ads.customer_id,
         campaign_id=campaign_id,
         image_paths=image_paths,
+        image_urls=image_urls,
     )
 
 
@@ -2799,6 +2823,7 @@ def run_reddit_report(
     (HOUR and DATE cannot be combined). Dates are account-local days.
     filter: Reddit filter expression (e.g. "campaign_id==abc123").
     Microcurrency fields are converted to currency amounts.
+    Queries the Reddit Ads API: https://ads-api.reddit.com/docs/v3/
     """
     from adloop.reddit.read import run_reddit_report as _impl
 
@@ -3718,8 +3743,8 @@ def get_brand_lists(
 ) -> dict:
     """List all brand lists (SharedSets of type BRANDS) in the account.
 
-    Returns each list's ID, name, status, and member count. Call this before
-    propose_brand_list so an existing list can be reused instead of duplicated.
+    Returns each list's ID, name, status, and member count. Useful before
+    propose_brand_list, so an existing list can be reused instead of duplicated.
 
     Args:
         customer_id: Ads account ID. Defaults to the configured account.