adloop 0.32.1__tar.gz → 0.33.1__tar.gz

{adloop-0.32.1 → adloop-0.33.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: adloop
-Version: 0.32.1
+Version: 0.33.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

{adloop-0.32.1 → adloop-0.33.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "adloop"
-version = "0.32.1"
+version = "0.33.1"
 description = "The AI command center for Google Ads, Reddit Ads, GA4, and tracking code."
 readme = "README.md"
 requires-python = ">=3.11"

{adloop-0.32.1 → adloop-0.33.1}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "adloop"
-version = "0.32.1"
+version = "0.33.1"
 description = "The AI command center for Google Ads, Reddit Ads, GA4, and tracking code."
 readme = "README.md"
 authors = [

{adloop-0.32.1 → adloop-0.33.1}/src/adloop/ads/conversion_actions.py

@@ -25,6 +25,7 @@ import hashlib
 import math
 import re
 import threading
+from dataclasses import dataclass
 from datetime import datetime, timezone as _tz
 from typing import TYPE_CHECKING, Callable
 
@@ -1009,8 +1010,16 @@ _CSV_COMMENT_PREFIX = "#"
 _MAX_CSV_BYTES = 5 * 1024 * 1024
 
 
+@dataclass(frozen=True)
+class UploadedCsv:
+    """A conversion CSV that arrived as an upload instead of a local path."""
+
+    name: str
+    data: bytes
+
+
 def _read_upload_csv(
-    csv_path: str,
+    csv_path: "str | UploadedCsv",
 ) -> tuple[list[tuple[int, list[str]]], list[str], str]:
     """Read an upload CSV into ``(source_line, cells)`` records (header first).
 
@@ -1020,8 +1029,9 @@ def _read_upload_csv(
     Counting records instead would drift as soon as a comment or a bad row is
     dropped.
 
-    Local-only by design: the path is read from the machine running AdLoop, so
-    the tool refuses in server mode before it gets here. Errors name the file
+    ``csv_path`` is a path on the machine running AdLoop (refused in server
+    mode before it gets here) or an :class:`UploadedCsv` from the upload
+    store, which a hosted server reads instead. Errors name the file
     and the schema, never file *content* — a hosted runtime can read files the
     caller is not allowed to see.
     """
@@ -1036,15 +1046,21 @@ def _read_upload_csv(
     # which is what timestamps without an offset are resolved against.
     timezone = ""
 
-    path = Path(csv_path).expanduser()
-    if not path.is_file():
-        return [], [f"CSV not found or not a regular file: {path}"], ""
-    if path.suffix.lower() != ".csv":
-        return [], [f"CSV must be a .csv file, got: {path.name}"], ""
-    try:
-        size = path.stat().st_size
-    except OSError as exc:
-        return [], [f"CSV could not be read: {exc.strerror or exc}"], ""
+    import io
+
+    if isinstance(csv_path, UploadedCsv):
+        path = None
+        size = len(csv_path.data)
+    else:
+        path = Path(csv_path).expanduser()
+        if not path.is_file():
+            return [], [f"CSV not found or not a regular file: {path}"], ""
+        if path.suffix.lower() != ".csv":
+            return [], [f"CSV must be a .csv file, got: {path.name}"], ""
+        try:
+            size = path.stat().st_size
+        except OSError as exc:
+            return [], [f"CSV could not be read: {exc.strerror or exc}"], ""
     if size > _MAX_CSV_BYTES:
         return [], [
             f"CSV is {size / 1_048_576:.1f} MB; the limit is "
@@ -1053,7 +1069,11 @@ def _read_upload_csv(
         ], ""
 
     try:
-        with path.open("r", newline="", encoding="utf-8-sig") as handle:
+        with (
+            io.StringIO(csv_path.data.decode("utf-8-sig"), newline="")
+            if path is None
+            else path.open("r", newline="", encoding="utf-8-sig")
+        ) as handle:
             position = {"line": 0}
 
             def _lines():
@@ -1164,7 +1184,7 @@ def _pad_to_header(raw: list[str], columns: int) -> list[str]:
 
 
 def _parse_call_conversion_csv(
-    csv_path: str, default_region: str = ""
+    csv_path: "str | UploadedCsv", default_region: str = ""
 ) -> tuple[list[dict], list[str], list[str], list[dict]]:
     """Read the call-conversions CSV (local file) and normalize each row.
 
@@ -1310,7 +1330,8 @@ def draft_upload_call_conversions(
     config: AdLoopConfig,
     *,
     customer_id: str = "",
-    csv_path: str,
+    csv_path: str = "",
+    upload_id: str = "",
     default_region: str = "",
     consent: dict | None = None,
 ) -> dict:
@@ -1353,12 +1374,17 @@ def draft_upload_call_conversions(
         operation="upload_call_conversions",
         default_region=default_region,
         consent=consent,
+        csv_path=csv_path,
+        upload_id=upload_id,
     )
+    if error:
+        return error
+    source, error = _csv_source(csv_path, upload_id)
     if error:
         return error
 
     rows, parse_advisories, skipped, error = _upload_parse_result(
-        *_parse_call_conversion_csv(csv_path, default_region),
+        *_parse_call_conversion_csv(source, default_region),
         empty_message="CSV contained zero conversion rows",
     )
     if error:
@@ -1493,7 +1519,7 @@ def draft_upload_call_conversions(
         apply_only_payload={"rows": frozen_rows},
     )
     store_plan(plan)
-    return plan.to_preview()
+    return _consume_upload(plan.to_preview(), upload_id)
 
 
 def _resolve_upload_action(
@@ -1714,6 +1740,8 @@ def _upload_draft_preflight(
     operation: str,
     default_region: str,
     consent: dict | None,
+    csv_path: str = "",
+    upload_id: str = "",
 ) -> tuple[str, dict | None, dict | None]:
     """The guards both upload drafts run before they touch the CSV.
 
@@ -1724,12 +1752,19 @@ def _upload_draft_preflight(
     from adloop.runtime import deployment_mode
     from adloop.safety.guards import SafetyViolation, check_blocked_operation
 
-    if deployment_mode() == "server":
+    if bool(csv_path) == bool(upload_id):
+        return "", None, {
+            "error": (
+                "Pass exactly one of csv_path (a file on the machine running "
+                "AdLoop) or upload_id (a CSV uploaded with upload_conversion_csv)."
+            )
+        }
+    if csv_path and deployment_mode() == "server":
         return "", None, {
             "error": (
-                "This tool uploads conversions from a CSV file on the machine "
-                "running AdLoop and is not available on the hosted server. "
-                "Use the self-hosted AdLoop MCP server for conversion uploads."
+                "csv_path names a file on the machine running AdLoop, which on "
+                "the hosted server is not yours. Upload the CSV with "
+                "upload_conversion_csv and pass its upload_id instead."
             )
         }
 
@@ -1754,6 +1789,37 @@ def _upload_draft_preflight(
     return region, consent_norm, None
 
 
+def _csv_source(csv_path: str, upload_id: str) -> "tuple[str | UploadedCsv | None, dict | None]":
+    """The CSV to parse: the local path, or the uploaded file's bytes."""
+    if not upload_id:
+        return csv_path, None
+    from adloop.uploads import UploadError, current_tenant, get_upload_store
+
+    try:
+        upload, data = get_upload_store().get(current_tenant(), upload_id, kind="csv")
+    except UploadError as exc:
+        return None, {"error": f"{exc}. Upload the CSV again with upload_conversion_csv."}
+    return UploadedCsv(name=upload.name, data=data), None
+
+
+def _consume_upload(preview: dict, upload_id: str) -> dict:
+    """Delete an uploaded CSV once its plan holds the rows.
+
+    The plan carries everything apply needs, so the raw file (phone numbers,
+    emails) has no reason to stay. A draft that failed keeps the file, so a
+    retry with another default_region needs no new upload.
+    """
+    if upload_id:
+        from adloop.uploads import current_tenant, get_upload_store
+
+        get_upload_store().delete(current_tenant(), upload_id)
+        preview["source_upload"] = (
+            f"{upload_id} was read and deleted; the plan holds the rows. A new "
+            "draft needs a new upload."
+        )
+    return preview
+
+
 def _upload_parse_result(
     rows: list[dict],
     errors: list[str],
@@ -2262,7 +2328,7 @@ _OPTIONAL_EC_HEADERS = [
 
 
 def _parse_ec_for_leads_csv(
-    csv_path: str, default_region: str = ""
+    csv_path: "str | UploadedCsv", default_region: str = ""
 ) -> tuple[list[dict], list[str], list[str], list[dict]]:
     """Parse the EC-for-Leads CSV (local file) and hash PII at parse time.
 
@@ -2463,7 +2529,8 @@ def draft_upload_enhanced_conversions_for_leads(
     config: AdLoopConfig,
     *,
     customer_id: str = "",
-    csv_path: str,
+    csv_path: str = "",
+    upload_id: str = "",
     default_region: str = "",
     consent: dict | None = None,
 ) -> dict:
@@ -2501,12 +2568,17 @@ def draft_upload_enhanced_conversions_for_leads(
         operation="upload_enhanced_conversions_for_leads",
         default_region=default_region,
         consent=consent,
+        csv_path=csv_path,
+        upload_id=upload_id,
     )
+    if error:
+        return error
+    source, error = _csv_source(csv_path, upload_id)
     if error:
         return error
 
     rows, parse_advisories, skipped, error = _upload_parse_result(
-        *_parse_ec_for_leads_csv(csv_path, default_region),
+        *_parse_ec_for_leads_csv(source, default_region),
         empty_message="CSV contained zero conversion rows",
     )
     if error:
@@ -2735,7 +2807,7 @@ def draft_upload_enhanced_conversions_for_leads(
         apply_only_payload={"rows": frozen_rows},
     )
     store_plan(plan)
-    return plan.to_preview()
+    return _consume_upload(plan.to_preview(), upload_id)
 
 
 def _apply_upload_enhanced_conversions_for_leads(

{adloop-0.32.1 → adloop-0.33.1}/src/adloop/ads/write.py

@@ -3351,7 +3351,7 @@ def image_payloads(
         from adloop.uploads import UploadError, current_tenant, get_upload_store
 
         try:
-            upload, _data = get_upload_store().get(current_tenant(), upload_id)
+            upload, _data = get_upload_store().get(current_tenant(), upload_id, kind="image")
         except UploadError as exc:
             errors.append(f"Upload {index + 1}: {exc}")
             continue
@@ -5135,7 +5135,7 @@ def load_image_bytes(payload: dict) -> tuple[bytes, PurePath]:
     if payload.get("upload_id"):
         from adloop.uploads import current_tenant, get_upload_store
 
-        upload, image_bytes = get_upload_store().get(current_tenant(), str(payload["upload_id"]))
+        upload, image_bytes = get_upload_store().get(current_tenant(), str(payload["upload_id"]), kind="image")
         if upload.sha256 != payload.get("sha256"):
             raise ValueError(f"upload {upload.upload_id} changed since the preview; draft again.")
         return image_bytes, PurePosixPath(upload.name)

{adloop-0.32.1 → adloop-0.33.1}/src/adloop/rules/adloop.md

@@ -249,6 +249,21 @@ For images that have no public URL: a file on the user's computer, or an image t
 - **Using an upload:** `draft_image_assets(upload_ids=["up_..."])` for Google Ads; `"upload:up_..."` as `image_url`, `thumbnail_url` or a carousel card's `image_url` in `draft_reddit_ad` (AdLoop Cloud only, because Reddit downloads the image from a short-lived public link). Videos cannot be uploaded.
 - Uploads expire after 24 hours. Self-hosted without a card, pass local files directly (`image_paths`).
 
+### Offline Conversion Uploads
+
+Conversions that happen offline (a sales call, a lead that turned into a deal) go back to Google Ads from a CSV in Google's upload template.
+
+| Tool | When to Use | Key Parameters |
+|------|-------------|----------------|
+| `upload_conversion_csv` | The CSV is not on the machine running AdLoop (always on AdLoop Cloud). Shows the upload card, or returns an upload link | (none) |
+| `draft_upload_call_conversions` | Calls from call assets or call-tracking numbers that became a conversion; matched by the caller's phone number | exactly one of `csv_path` (local file) or `upload_id`; `default_region` for numbers without a country code; `consent` |
+| `draft_upload_enhanced_conversions_for_leads` | Form leads that became a conversion; matched by hashed email, phone or name and address | exactly one of `csv_path` or `upload_id`; `default_region`; `consent` |
+
+- The conversion action named in the CSV's `Conversion Name` column must exist and be of type UPLOAD_CALLS (calls) or UPLOAD_CLICKS (leads); the draft checks it against the account.
+- **The CSV holds personal data** (phone numbers, emails, names). An uploaded file lasts two hours at most and is deleted as soon as a draft has read it, so a second draft needs a new upload; a failed draft keeps it for a retry (for example with `default_region`). Lead identifiers are hashed while drafting. Never ask the user to paste rows into the chat.
+- EEA traffic needs consent signals: pass `consent` or fill the CSV's `Ad User Data` / `Ad Personalization` columns. Present the preview's `consent_summary`, `skipped_rows` and `dedup_warnings`.
+- Apply sends batches of 2,000 rows. `PARTIAL_UPLOAD` means some batches are already in the account: the plan is retired, and a new draft continues at `resume_from_line`. Don't re-upload rows that went through.
+
 ### Planning Tools
 
 | Tool | When to Use | Key Parameters |
@@ -330,7 +345,7 @@ Same draft → preview → `confirm_and_apply` gate; the plan carries `platform:
 
 **Approval cards (Claude, ChatGPT, VS Code and other apps with MCP Apps):** when the preview comes back with `approval: "card"`, the user sees it as an AdLoop approval card with Test run, Apply and Discard buttons, and approves there. Summarize the change and its warnings, then let the user decide on the card instead of asking for a "yes" in the chat. In those apps `confirm_and_apply(dry_run=false)` is refused with status `APPROVE_ON_CARD` (a dry run still works), because only the click applies; the AI cannot press the button. Do not retry. If the user says the card is not visible, tell them the workspace owner can allow approval in chat (AdLoop Cloud: Settings → Safety; self-hosted: `safety.allow_chat_approval`). After a click the card posts a message such as "Applied on the AdLoop approval card: ..."; continue from there (e.g. remind them to enable a new paused ad).
 
-**Confirmation dialogs (apps without cards that support elicitation):** when you call `confirm_and_apply(dry_run=false)` after the user's go-ahead, AdLoop itself asks the user in the app's confirmation dialog before anything changes; irreversible changes need an extra "cannot be undone" tick there. You do not answer that dialog. `NOT_CONFIRMED` means the user declined or closed it: nothing was changed, the preview stays pending, so ask what they want instead of retrying. Apps with neither cards nor dialogs keep the chat flow above.
+**Confirmation dialogs (apps without cards that support elicitation):** when you call `confirm_and_apply(dry_run=false)` after the user's go-ahead, AdLoop itself asks the user in the app's confirmation dialog before anything changes; irreversible changes need an extra "cannot be undone" tick there. You do not answer that dialog. `NOT_CONFIRMED` means the user declined or closed it: nothing was changed, the preview stays pending, so ask what they want instead of retrying. A dry run's `next_step` says when a dialog will follow, so tell the user to look out for it. `CONFIRMATION_UNANSWERED` means the app received the dialog but never returned an answer (some headless agents and IDE setups declare dialogs they cannot show): nothing was changed; ask the user whether a dialog appeared, and if their app cannot show one, relay the message's ways out (approval in chat, or an app with the approval card). Apps with neither cards nor dialogs keep the chat flow above.
 
 **Safety behaviors:**
 - New campaigns and RSAs (and every Reddit campaign, ad group and ad) are created as PAUSED — user must explicitly enable them after review.

{adloop-0.32.1 → adloop-0.33.1}/src/adloop/safety/approval.py

@@ -335,6 +335,64 @@ def _not_confirmed(plan: ChangePlan) -> dict:
     }
 
 
+def _dialog_unanswered(plan: ChangePlan) -> dict:
+    return {
+        "status": "CONFIRMATION_UNANSWERED",
+        "plan_id": plan.plan_id,
+        "operation": plan.operation,
+        "message": (
+            "AdLoop asked the user to confirm this change in a dialog of their app, "
+            "but the app never returned an answer, so nothing was changed and the "
+            "plan stays pending. Ask the user whether a confirmation dialog appeared. "
+            "If it did, call confirm_and_apply again and have them answer it. If their "
+            "app cannot show dialogs (for example a headless agent or a script), the "
+            "workspace owner can allow approval in chat (AdLoop Cloud: Settings -> "
+            "Safety -> 'Also allow approval in chat'; self-hosted: "
+            "safety.allow_chat_approval: true), or the change can be applied from an "
+            "app that shows AdLoop's approval card, such as Claude or ChatGPT. Calling "
+            "confirm_and_apply again sends the dialog once more."
+        ),
+    }
+
+
+def _mark_dialog(plan: ChangePlan, open_: bool) -> None:
+    """Record (or clear) that a dialog for this plan awaits an answer."""
+    from datetime import datetime, timezone
+
+    from adloop.safety.preview import store_plan
+
+    plan.dialog_requested_at = datetime.now(timezone.utc).isoformat() if open_ else ""
+    store_plan(plan)
+
+
+def dialog_expected(plan_id: str) -> bool:
+    """Whether a real apply of this plan will ask the user in a dialog.
+
+    Used after a successful dry run, so the AI can tell the user to look out
+    for it instead of letting an unanswered dialog look like a hang.
+    """
+    if _dialog_applies(plan_id) is None:
+        return False
+    try:
+        from fastmcp.server.dependencies import get_context
+
+        if get_context()._is_modern_protocol():
+            return True
+    except Exception:
+        return False
+    from adloop.runtime import deployment_mode
+
+    # Older protocols get the dialog only self-hosted (see confirm_in_dialog).
+    return deployment_mode() != "server"
+
+
+DIALOG_NOTE = (
+    "The real apply (dry_run=false) asks the user to confirm in a dialog shown by "
+    "their app; tell them to look out for it and answer it. If no dialog appears, "
+    "the call returns CONFIRMATION_UNANSWERED on the next attempt with the ways out."
+)
+
+
 def _dialog_applies(plan_id: str) -> ChangePlan | None:
     """The plan when a real apply must be confirmed in a dialog, else None."""
     from adloop.runtime import current_config
@@ -375,6 +433,14 @@ async def confirm_in_dialog(context: Any, plan_id: str) -> Any | None:
     if context._is_modern_protocol():
         responses = context.input_responses
         if responses is None:
+            if plan.dialog_requested_at:
+                # The last dialog for this plan was sent and this is a fresh
+                # call, not its answer: the app received the dialog and never
+                # returned one. Say so instead of sending another dialog the
+                # app will sit on until its timeout. Cleared, so asking again
+                # sends a new dialog.
+                _mark_dialog(plan, False)
+                return ToolResult(structured_content=_dialog_unanswered(plan))
             import mcp_types
             from fastmcp.tools.base import InputRequiredToolResult
 
@@ -385,11 +451,14 @@ async def confirm_in_dialog(context: Any, plan_id: str) -> Any | None:
                 )
             )
             state = json.dumps({"plan_id": plan.plan_id, "code": approval_code(plan)})
+            _mark_dialog(plan, True)
             return InputRequiredToolResult(
                 mcp_types.InputRequiredResult(
                     input_requests={DIALOG_KEY: request}, request_state=state
                 )
             )
+        if plan.dialog_requested_at:
+            _mark_dialog(plan, False)  # answered, whatever the answer is
         try:
             state = json.loads(context.request_state or "{}")
         except ValueError:

{adloop-0.32.1 → adloop-0.33.1}/src/adloop/safety/preview.py

@@ -25,6 +25,11 @@ class ChangePlan:
     # Ad platform the plan targets: "" (Google, the default so stored plans
     # from before the field existed still load) or "reddit".
     platform: str = ""
+    # When a confirmation dialog for this plan was last sent and not yet
+    # answered (ISO timestamp, "" when none is open). An app that receives
+    # the dialog but never answers it would otherwise leave every retry
+    # waiting until its own timeout; see approval.confirm_in_dialog.
+    dialog_requested_at: str = ""
 
     # Payload the applier needs but a preview must never show: an upload's rows
     # (the caller id cannot be hashed, so call uploads carry raw phone numbers),

{adloop-0.32.1 → adloop-0.33.1}/src/adloop/server.py

@@ -4482,6 +4482,11 @@ def confirm_and_apply(
     only the user's click on the card applies the change. Dry runs still
     work. The workspace owner can allow approval in chat as well.
 
+    Confirmation dialogs: in apps that show dialogs instead, dry_run=false
+    first asks the user in a dialog. A declined dialog returns NOT_CONFIRMED;
+    an app that receives the dialog but never answers it gets
+    CONFIRMATION_UNANSWERED on the next call, with the ways out.
+
     Args:
         plan_id: The plan_id returned by a prior draft_*, update_*, add_*,
             pause/enable/remove or other preview tool call. An unknown or
@@ -4490,13 +4495,17 @@ def confirm_and_apply(
             applies the change for real.
     """
     from adloop.ads.write import confirm_and_apply as _impl
-    from adloop.safety.approval import chat_apply_refusal
+    from adloop.safety.approval import DIALOG_NOTE, chat_apply_refusal, dialog_expected
 
     if not dry_run:
         refusal = chat_apply_refusal(plan_id)
         if refusal is not None:
             return refusal
-    return _impl(current_config(), plan_id=plan_id, dry_run=dry_run)
+    result = _impl(current_config(), plan_id=plan_id, dry_run=dry_run)
+    if (dry_run and isinstance(result, dict) and result.get("status") == "DRY_RUN_SUCCESS"
+            and dialog_expected(plan_id)):
+        result["next_step"] = DIALOG_NOTE
+    return result
 
 
 @_tool(
@@ -4590,10 +4599,15 @@ def upload_images() -> dict:
     draft_image_assets, or as "upload:<id>" into the image fields of
     draft_reddit_ad. Returns the current uploads and how to add more.
     """
+    return _upload_tool_result("image")
+
+
+def _upload_tool_result(kind: str):
+    """The upload card (with its code) or the upload link, for ``kind``."""
     from adloop.uploads import upload_instructions
 
     shows_cards = client_shows_cards()
-    result = upload_instructions(shows_cards)
+    result = upload_instructions(shows_cards, kind)
     if not shows_cards:
         return result
     from fastmcp.tools import ToolResult
@@ -4609,6 +4623,29 @@ def upload_images() -> dict:
     )
 
 
+@_tool(
+    title="Upload a conversion CSV",
+    annotations=_READONLY,
+    tags={"ads"},
+    meta={"ui": {"resourceUri": UPLOAD_CARD_URI}},
+)
+@_safe
+def upload_conversion_csv() -> dict:
+    """Let the user upload a conversion CSV for an offline conversion upload.
+
+    For the CSV behind draft_upload_call_conversions or
+    draft_upload_enhanced_conversions_for_leads when the file is not on the
+    machine running AdLoop, as on AdLoop Cloud. Apps that show AdLoop's
+    cards display an upload card where the user drops the .csv file; the
+    card then posts the upload id into the chat. Other apps on AdLoop Cloud
+    get an upload link for the user (or a coding agent, with curl). The
+    file holds personal data (phone numbers, emails), so it is kept for two
+    hours at most and deleted as soon as a draft has read it. Returns the
+    CSV uploads waiting to be used and how to add one.
+    """
+    return _upload_tool_result("csv")
+
+
 @_tool(
     title="Store an uploaded image",
     annotations=_WRITE,
@@ -4616,16 +4653,19 @@ def upload_images() -> dict:
     meta={"ui": {"resourceUri": UPLOAD_CARD_URI, "visibility": ["app"]}},
 )
 @_safe
-def store_image_upload(name: str, data_base64: str, code: str = "") -> dict:
-    """Store an image dropped on the AdLoop upload card.
+def store_image_upload(name: str, data_base64: str, code: str = "", kind: str = "image") -> dict:
+    """Store a file dropped on the AdLoop upload card.
 
     Called only by the upload card; AI apps keep this tool out of the
-    model's tool list. Returns the upload's id, type and dimensions.
+    model's tool list. Returns the upload's id, type and size (dimensions
+    for images, lines for CSVs).
 
     Args:
         name: The file name, used for the asset name.
         data_base64: The file content, base64-encoded.
-        code: The upload card's code from upload_images.
+        code: The upload card's code from upload_images or
+            upload_conversion_csv.
+        kind: "image" (default) or "csv" for a conversion CSV.
     """
     import base64
     import binascii
@@ -4637,20 +4677,21 @@ def store_image_upload(name: str, data_base64: str, code: str = "") -> dict:
     except (binascii.Error, ValueError):
         return {"error": "The file did not arrive intact; upload it again."}
     try:
-        upload = get_upload_store().put(current_tenant(), name, data)
+        upload = get_upload_store().put(current_tenant(), name, data, kind=kind)
     except UploadError as exc:
         return {"error": f"{name}: {exc}"}
     return {"status": "UPLOADED", **upload.summary()}
 
 
-@_tool(title="List uploaded images", annotations=_READONLY, tags={"core"})
+@_tool(title="List uploads", annotations=_READONLY, tags={"core"})
 @_safe
 def list_uploads() -> dict:
-    """List the images the user uploaded to AdLoop that have not expired.
+    """List the files the user uploaded to AdLoop that have not expired.
 
-    Returns each upload's upload_id, name, type, dimensions, size and hours
-    until it expires (uploads last a day): the ids of files the user sent
-    through the upload link, or of earlier uploads.
+    Returns each upload's upload_id, kind (image or csv), name, type, size,
+    dimensions (images) or lines (CSVs) and hours until it expires: images
+    last a day, conversion CSVs two hours or until a draft reads them. The
+    ids of files the user sent through an upload link show up here.
     """
     from adloop.uploads import current_tenant, get_upload_store
 
@@ -4660,7 +4701,8 @@ def list_uploads() -> dict:
         "usage": (
             "draft_image_assets(upload_ids=[...]) for Google Ads; "
             "\"upload:<upload_id>\" as image_url, thumbnail_url or a carousel card's "
-            "image_url in draft_reddit_ad (AdLoop Cloud only)."
+            "image_url in draft_reddit_ad (AdLoop Cloud only). CSV uploads: upload_id in "
+            "draft_upload_call_conversions or draft_upload_enhanced_conversions_for_leads."
         ),
     }
 
@@ -6141,7 +6183,8 @@ def draft_remove_conversion_action(
 @_tool(title="Draft call conversion upload", annotations=_WRITE, tags={"ads"})
 @_safe
 def draft_upload_call_conversions(
-    csv_path: str,
+    csv_path: str = "",
+    upload_id: str = "",
     default_region: str = "",
     consent: dict | None = None,
     customer_id: str = "",
@@ -6157,8 +6200,9 @@ def draft_upload_call_conversions(
     drafting, so a typo fails here rather than after the upload. Optional
     `Ad User Data` and `Ad Personalization` columns carry consent per row.
 
-    Local file only: on the hosted server this tool refuses, because it would
-    read a path on the server rather than the caller's machine.
+    The CSV comes from csv_path (a file on the machine running AdLoop) or
+    from upload_id (a file uploaded with upload_conversion_csv, the only way
+    on AdLoop Cloud). An uploaded file is deleted once the draft has read it.
 
     PII: the caller phone number is required RAW by Google (it cannot be
     hashed), so it lives in the plan's apply-only payload — the preview shows
@@ -6181,8 +6225,10 @@ def draft_upload_call_conversions(
 
     Args:
         csv_path: Path of the CSV file holding the upload rows, read on the
-            machine that runs AdLoop. The hosted server refuses this tool
-            rather than reading a path of its own.
+            machine that runs AdLoop. Refused on the hosted server; use
+            upload_id there.
+        upload_id: Id of a CSV uploaded with upload_conversion_csv (up_...),
+            instead of csv_path.
         default_region: ISO 3166-1 alpha-2 country assumed for phone numbers
             that carry no country code, e.g. "DE" for "0151 12345678". Empty
             leaves such numbers unusable and the row is skipped.
@@ -6202,6 +6248,7 @@ def draft_upload_call_conversions(
         current_config(),
         customer_id=customer_id or current_config().ads.customer_id,
         csv_path=csv_path,
+        upload_id=upload_id,
         default_region=default_region,
         consent=consent,
     )
@@ -6210,7 +6257,8 @@ def draft_upload_call_conversions(
 @_tool(title="Draft enhanced conversions upload", annotations=_WRITE, tags={"ads"})
 @_safe
 def draft_upload_enhanced_conversions_for_leads(
-    csv_path: str,
+    csv_path: str = "",
+    upload_id: str = "",
     default_region: str = "",
     consent: dict | None = None,
     customer_id: str = "",
@@ -6235,8 +6283,9 @@ def draft_upload_enhanced_conversions_for_leads(
     sharing an Order ID count once at Google; two rows with different Order
     IDs are two real orders and are not reported.
 
-    Local file only: on the hosted server this tool refuses, because it would
-    read a path on the server rather than the caller's machine.
+    The CSV comes from csv_path (a file on the machine running AdLoop) or
+    from upload_id (a file uploaded with upload_conversion_csv, the only way
+    on AdLoop Cloud). An uploaded file is deleted once the draft has read it.
 
     Returns a preview with a plan_id, the row counts, the consent the rows
     actually carry (`consent_summary`) and the skipped rows; nothing is
@@ -6244,8 +6293,10 @@ def draft_upload_enhanced_conversions_for_leads(
 
     Args:
         csv_path: Path of the CSV file holding the upload rows, read on the
-            machine that runs AdLoop. The hosted server refuses this tool
-            rather than reading a path of its own.
+            machine that runs AdLoop. Refused on the hosted server; use
+            upload_id there.
+        upload_id: Id of a CSV uploaded with upload_conversion_csv (up_...),
+            instead of csv_path.
         default_region: ISO 3166-1 alpha-2 country assumed for phone numbers
             that carry no country code, e.g. "DE" for "0151 12345678". Empty
             leaves such numbers unusable; the row still uploads when its email
@@ -6266,6 +6317,7 @@ def draft_upload_enhanced_conversions_for_leads(
         current_config(),
         customer_id=customer_id or current_config().ads.customer_id,
         csv_path=csv_path,
+        upload_id=upload_id,
         default_region=default_region,
         consent=consent,
     )