adloop 0.25.0__tar.gz → 0.26.1__tar.gz

{adloop-0.25.0 → adloop-0.26.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: adloop
-Version: 0.25.0
+Version: 0.26.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
@@ -262,6 +262,19 @@ A second ad platform, same safety model. Reddit is a separate connection: its ow
 
 > **Setup for Reddit Ads tools** — In Reddit Ads Manager open **Business Manager → Developer Application → Create app** (business admins only; no approval wait). Register the redirect URL exactly as `http://localhost:8765/callback`, then run `adloop init` and complete the Reddit Ads step: it opens Reddit's consent page (scopes `adsread` + `adsedit`, permanent grant), stores the refresh token at `~/.adloop/reddit_token.json`, and lets you pick the default ad account. Reddit rate-limits per user (reporting: 60 requests/min) and requires a descriptive User-Agent, which AdLoop builds from your app id and Reddit username. Reddit has no validate-only mode, so `confirm_and_apply(dry_run=true)` re-reads the target and re-checks the safety caps instead.
 
+### Image Uploads
+
+An image on your computer, or one you attached in the chat, has no public URL, and an AI app cannot hand the file to a tool. `upload_images` gives it a way in.
+
+<p align="center"><img src="https://raw.githubusercontent.com/kLOsk/adloop/main/assets/upload-card.gif" alt="An AdLoop upload card in an AI chat: the user drags a banner onto it, the card shows the upload id, posts it into the chat, and the AI drafts the image asset" width="760"></p>
+
+| Tool | What It Does |
+|------|-------------|
+| `upload_images` | Shows an upload card in apps with MCP Apps (drop PNG, JPEG or GIF up to 5 MB); on AdLoop Cloud in other apps it returns a one-time upload link, which a coding agent can also use with `curl -T` |
+| `list_uploads` | The uploads that have not expired yet (kept 24 hours), with id, dimensions and size |
+
+The upload ids go into `draft_image_assets(upload_ids=[...])`, or as `upload:<id>` into the image fields of `draft_reddit_ad` on AdLoop Cloud.
+
 ### Planning Tools
 
 | Tool | What It Does |
@@ -282,7 +295,7 @@ 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 files or public image URLs (PNG, JPEG, or GIF). |
+| `draft_image_assets` | Create campaign image assets from local files, public image URLs or uploads (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 |
@@ -337,6 +350,10 @@ AdLoop includes pre-built slash commands in `.claude/commands/` for common workf
 
 AdLoop manages real ad spend, so safety is not optional.
 
+<p align="center"><img src="https://raw.githubusercontent.com/kLOsk/adloop/main/assets/approval-card.gif" alt="An AdLoop approval card in an AI chat: the user clicks Test run, Google validates the change, then Apply makes it live and the card reports back to the chat" width="760"></p>
+
+- **Approval cards.** In apps that show MCP Apps (Claude, ChatGPT, VS Code and others), every change appears as a card with Test run and Apply. Only the click applies it: the AI's own `confirm_and_apply(dry_run=false)` is refused with `APPROVE_ON_CARD`, whatever it was told in the chat.
+- **Confirmation dialogs.** Apps without cards that support elicitation (Claude Code, for example) get a dialog from AdLoop itself before every real change. The AI cannot answer it; declining changes nothing.
 - **Two-step writes.** Every mutation returns a preview first. A separate `confirm_and_apply` call is required to execute.
 - **Dry-run by default.** Even `confirm_and_apply` defaults to `dry_run=true`. Real changes require explicit `dry_run=false`.
 - **Two-phase apply (optional).** With `safety.two_phase_apply: true`, `confirm_and_apply` refuses `dry_run=false` until the plan has completed one dry-run pass — preview-then-apply becomes server-enforced instead of a convention.

{adloop-0.25.0 → adloop-0.26.1}/README.md

@@ -234,6 +234,19 @@ A second ad platform, same safety model. Reddit is a separate connection: its ow
 
 > **Setup for Reddit Ads tools** — In Reddit Ads Manager open **Business Manager → Developer Application → Create app** (business admins only; no approval wait). Register the redirect URL exactly as `http://localhost:8765/callback`, then run `adloop init` and complete the Reddit Ads step: it opens Reddit's consent page (scopes `adsread` + `adsedit`, permanent grant), stores the refresh token at `~/.adloop/reddit_token.json`, and lets you pick the default ad account. Reddit rate-limits per user (reporting: 60 requests/min) and requires a descriptive User-Agent, which AdLoop builds from your app id and Reddit username. Reddit has no validate-only mode, so `confirm_and_apply(dry_run=true)` re-reads the target and re-checks the safety caps instead.
 
+### Image Uploads
+
+An image on your computer, or one you attached in the chat, has no public URL, and an AI app cannot hand the file to a tool. `upload_images` gives it a way in.
+
+<p align="center"><img src="https://raw.githubusercontent.com/kLOsk/adloop/main/assets/upload-card.gif" alt="An AdLoop upload card in an AI chat: the user drags a banner onto it, the card shows the upload id, posts it into the chat, and the AI drafts the image asset" width="760"></p>
+
+| Tool | What It Does |
+|------|-------------|
+| `upload_images` | Shows an upload card in apps with MCP Apps (drop PNG, JPEG or GIF up to 5 MB); on AdLoop Cloud in other apps it returns a one-time upload link, which a coding agent can also use with `curl -T` |
+| `list_uploads` | The uploads that have not expired yet (kept 24 hours), with id, dimensions and size |
+
+The upload ids go into `draft_image_assets(upload_ids=[...])`, or as `upload:<id>` into the image fields of `draft_reddit_ad` on AdLoop Cloud.
+
 ### Planning Tools
 
 | Tool | What It Does |
@@ -254,7 +267,7 @@ 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 files or public image URLs (PNG, JPEG, or GIF). |
+| `draft_image_assets` | Create campaign image assets from local files, public image URLs or uploads (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 |
@@ -309,6 +322,10 @@ AdLoop includes pre-built slash commands in `.claude/commands/` for common workf
 
 AdLoop manages real ad spend, so safety is not optional.
 
+<p align="center"><img src="https://raw.githubusercontent.com/kLOsk/adloop/main/assets/approval-card.gif" alt="An AdLoop approval card in an AI chat: the user clicks Test run, Google validates the change, then Apply makes it live and the card reports back to the chat" width="760"></p>
+
+- **Approval cards.** In apps that show MCP Apps (Claude, ChatGPT, VS Code and others), every change appears as a card with Test run and Apply. Only the click applies it: the AI's own `confirm_and_apply(dry_run=false)` is refused with `APPROVE_ON_CARD`, whatever it was told in the chat.
+- **Confirmation dialogs.** Apps without cards that support elicitation (Claude Code, for example) get a dialog from AdLoop itself before every real change. The AI cannot answer it; declining changes nothing.
 - **Two-step writes.** Every mutation returns a preview first. A separate `confirm_and_apply` call is required to execute.
 - **Dry-run by default.** Even `confirm_and_apply` defaults to `dry_run=true`. Real changes require explicit `dry_run=false`.
 - **Two-phase apply (optional).** With `safety.two_phase_apply: true`, `confirm_and_apply` refuses `dry_run=false` until the plan has completed one dry-run pass — preview-then-apply becomes server-enforced instead of a convention.

{adloop-0.25.0 → adloop-0.26.1}/pyproject.toml

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

{adloop-0.25.0 → adloop-0.26.1}/pyproject.toml.orig

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

{adloop-0.25.0 → adloop-0.26.1}/src/adloop/ads/write.py

@@ -432,7 +432,7 @@ def _size_kb(data: bytes) -> float:
 
 def _describe_image(image: dict[str, object]) -> str:
     """One preview line: source, type, dimensions and size."""
-    source = image.get("url") or image.get("path")
+    source = image.get("url") or image.get("path") or f"upload {image.get('upload_id')}"
     kind = str(image.get("mime_type", "")).removeprefix("image/").upper()
     return (
         f"{source} — {kind} {image.get('width')}x{image.get('height')}, "
@@ -2457,12 +2457,14 @@ def draft_image_assets(
     campaign_id: str = "",
     image_paths: list[str] | None = None,
     image_urls: list[str] | None = None,
+    upload_ids: list[str] | None = None,
 ) -> dict:
-    """Draft campaign image assets from local files and/or public image URLs.
+    """Draft campaign image assets from local files, public image URLs and/or uploads.
 
     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.
+    in the plan; apply re-fetches and refuses if the bytes changed. Uploads
+    (``up_...`` ids from the upload card or link) are pinned the same way.
     """
     from adloop.runtime import deployment_mode
     from adloop.safety.guards import SafetyViolation, check_blocked_operation
@@ -2486,7 +2488,7 @@ def draft_image_assets(
         return {"error": str(e)}
 
     validated_images, errors = _validate_image_assets(
-        campaign_id, image_paths, image_urls
+        campaign_id, image_paths, image_urls, list(upload_ids or [])
     )
     if errors:
         return {"error": "Validation failed", "details": errors}
@@ -3300,16 +3302,38 @@ def _validate_structured_snippets(
 
 
 def _validate_image_assets(
-    campaign_id: str, image_paths: list[str], image_urls: list[str] | None = None
+    campaign_id: str,
+    image_paths: list[str],
+    image_urls: list[str] | None = None,
+    upload_ids: list[str] | None = None,
 ) -> tuple[list[dict[str, object]], list[str]]:
     errors = []
     validated = []
     image_urls = image_urls or []
+    upload_ids = upload_ids or []
 
     if not campaign_id:
         errors.append("campaign_id is required")
-    if not image_paths and not image_urls:
-        errors.append("At least one image (image_paths or image_urls) is required")
+    if not image_paths and not image_urls and not upload_ids:
+        errors.append("At least one image (image_paths, image_urls or upload_ids) is required")
+
+    for index, upload_id in enumerate(upload_ids):
+        from adloop.uploads import UploadError, current_tenant, get_upload_store
+
+        try:
+            upload, _data = get_upload_store().get(current_tenant(), upload_id)
+        except UploadError as exc:
+            errors.append(f"Upload {index + 1}: {exc}")
+            continue
+        validated.append({
+            "upload_id": upload.upload_id,
+            "sha256": upload.sha256,
+            "name": _build_image_asset_name(PurePosixPath(upload.name), _data),
+            "mime_type": upload.mime_type,
+            "width": upload.width,
+            "height": upload.height,
+            "size_kb": round(upload.size_bytes / 1024, 1),
+        })
 
     for index, image_path in enumerate(image_paths):
         try:
@@ -4916,6 +4940,13 @@ def _apply_create_image_assets(client: object, cid: str, changes: dict) -> dict:
         if payload.get("url"):
             image_bytes = _fetch_approved_image_url(payload)
             name_source = _url_path(str(payload["url"]))
+        elif 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"]))
+            if upload.sha256 != payload.get("sha256"):
+                raise ValueError(f"upload {upload.upload_id} changed since the preview; draft again.")
+            name_source = PurePosixPath(upload.name)
         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.

{adloop-0.25.0 → adloop-0.26.1}/src/adloop/reddit/write.py

@@ -1595,6 +1595,40 @@ def _check_media(url: str, kind: str, timeout: int = 10) -> tuple[str | None, st
     return None, None
 
 
+def _media_problem(url: str, kind: str) -> tuple[str | None, str | None]:
+    """Check a media field: an ``upload:<id>`` reference, or a URL Reddit downloads."""
+    from adloop.uploads import UploadError, public_url_for, upload_ref
+
+    upload_id = upload_ref(url)
+    if upload_id is None:
+        return _check_media(url, kind)
+    if kind == "video":
+        return "is an upload; videos cannot be uploaded to AdLoop, pass a public video URL", None
+    try:
+        public_url_for(upload_id)
+    except UploadError as exc:
+        return f"cannot be used: {exc}", None
+    return None, None
+
+
+def _resolve_uploads(post: dict) -> dict:
+    """Swap ``upload:<id>`` media references for links Reddit can download now."""
+    from adloop.uploads import public_url_for, upload_ref
+
+    def swap(value: Any) -> Any:
+        upload_id = upload_ref(value) if isinstance(value, str) else None
+        return public_url_for(upload_id) if upload_id else value
+
+    resolved = dict(post)
+    if "thumbnail_url" in resolved:
+        resolved["thumbnail_url"] = swap(resolved["thumbnail_url"])
+    resolved["content"] = [
+        {**item, "media_url": swap(item.get("media_url"))} if isinstance(item, dict) else item
+        for item in resolved.get("content") or []
+    ]
+    return resolved
+
+
 def _carousel_content(
     cards: list | None, *, click_url: str, call_to_action: str, display_url: str, errors: list[str]
 ) -> list[dict]:
@@ -1757,15 +1791,20 @@ def draft_reddit_ad(
     from adloop.ads.write import _validate_urls
 
     landing = list(dict.fromkeys([click_url] + [c["destination_url"] for c in cards]))
-    url_errors, url_warnings = _validate_urls(landing + ([image_url] if image_url else []))
+    from adloop.uploads import upload_ref
+
+    image_is_upload = upload_ref(image_url) is not None
+    url_errors, url_warnings = _validate_urls(landing + ([image_url] if image_url and not image_is_upload else []))
     for url, problem in url_errors.items():
         if problem:
             errors.append(f"'{url}' is not reachable: {problem}")
     warnings.extend(url_warnings.values())
     media = [(video_url, "video"), (thumbnail_url, "image")] if post_type == "VIDEO" else []
     media += [(c["media_url"], "image") for c in cards]
+    if image_is_upload:
+        media.append((image_url, "image"))
     for url, kind in media:
-        problem, note = _check_media(url, kind)
+        problem, note = _media_problem(url, kind)
         if problem:
             errors.append(f"'{url}' {problem}")
         if note:
@@ -2185,7 +2224,8 @@ def apply_plan(config: AdLoopConfig, plan: ChangePlan) -> dict:
             post_id = str(changes["existing_post_id"])
             post = get_reddit_post(config, post_id) or {"id": post_id}
         else:
-            post = data_of(reddit_post(config, f"profiles/{profile_id}/posts", {"data": changes["post"]}))
+            post_payload = _resolve_uploads(changes["post"])
+            post = data_of(reddit_post(config, f"profiles/{profile_id}/posts", {"data": post_payload}))
             post_id = post.get("id")
             if not post_id:
                 raise ValueError("Reddit created the post but returned no post id; check Ads Manager.")

{adloop-0.25.0 → adloop-0.26.1}/src/adloop/rules/adloop.md

@@ -225,6 +225,20 @@ Reddit is a second ad platform with its own connection (own OAuth app, no develo
 5. `gtm_paused_but_firing` means the event reaches GA4 from somewhere other than the paused tag — hardcoded gtag, another container, or a mobile SDK; don't advise unpausing without finding the real source first
 6. Remember dynamic-event tags (`{{Event}}`) and Custom HTML tags are opaque to the audit — the tool lists them separately for manual review
 
+### Image Uploads
+
+For images that have no public URL: a file on the user's computer, or an image they attached in the chat. **Attaching an image to the chat does not get it into an ad:** you can see it, but no tool can receive it. Never suggest attaching as the way in; offer `upload_images` (card or link) or a public image URL, and when the user already attached one, ask them to drop the same file on the upload card.
+
+| Tool | When to Use | Key Parameters |
+|------|-------------|----------------|
+| `upload_images` | The user wants such an image in an ad. Apps with AdLoop cards show an upload card; on AdLoop Cloud in other apps the result has an `upload_url` | (none) |
+| `list_uploads` | Find upload ids after the user used the upload link, or to reuse an earlier upload | (none) |
+
+- **With the card** (`upload: "card"` in the result): the user drops PNG, JPEG or GIF files (up to 5 MB) on the card; it then posts the upload ids into the chat. Wait for that message instead of asking for a URL.
+- **With an upload link** (`upload_url`): give the user the link (valid 30 minutes) to open in the browser, then call `list_uploads` once they say they are done. A coding agent that has the file on disk can upload it itself: `curl -T "logo.png" "<upload_url>/"`, one call per file.
+- **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`).
+
 ### Planning Tools
 
 | Tool | When to Use | Key Parameters |
@@ -245,7 +259,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 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_image_assets` | Create image assets for a campaign from local files, public image URLs or uploads (does NOT publish) | `campaign_id`, `image_paths` (local PNG/JPEG/GIF files; not on a hosted server), `image_urls` (public http(s) image links, ≤5120 KB; re-checked at apply — if the image changed since the preview, draft again) and/or `upload_ids` (`up_...` from `upload_images` / `list_uploads`) |
 | `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.25.0 → adloop-0.26.1}/src/adloop/server.py

@@ -15,6 +15,7 @@ from pydantic import BeforeValidator
 
 from adloop import diagnostics
 from adloop.runtime import current_config
+from adloop.uploads import STORE_UPLOAD_TOOL, UPLOAD_CARD_URI
 from adloop.safety.approval import (
     APPROVE_TOOL,
     CARD_MIME_TYPE,
@@ -144,7 +145,13 @@ def _build_orchestration_instructions() -> str:
         "rejected too. Per-row problems in an upload are not a rejection: they "
         "come back as `row_errors` with DRY_RUN_SUCCESS, and the apply would "
         "carry out the other rows.\n"
-        "- One change at a time — don't batch unrelated writes.\n\n"
+        "- One change at a time — don't batch unrelated writes.\n"
+        "- Images without a public URL (a file on the user's computer, or one "
+        "attached in the chat): call `upload_images`, which shows an upload card "
+        "or returns an upload link, then use the upload ids it yields. An image "
+        "attached to the chat cannot be passed to any tool, so don't suggest "
+        "attaching as the way to get it into an ad; offer the upload or a public "
+        "image URL.\n\n"
         "PRE-WRITE CHECKS (before any `draft_*`):\n"
         "- BROAD match keywords require Smart Bidding (MAXIMIZE_CONVERSIONS, "
         "tCPA, tROAS). Refuse BROAD on MANUAL_CPC. This is the #1 cause of "
@@ -211,6 +218,27 @@ def approval_card() -> str:
     return card_html()
 
 
+@mcp.resource(
+    UPLOAD_CARD_URI,
+    name="upload_card",
+    title="AdLoop image upload",
+    description="A drop zone that uploads images to AdLoop for use as ad assets.",
+    mime_type=CARD_MIME_TYPE,
+    meta={"ui": {"prefersBorder": False}},
+)
+def upload_card() -> str:
+    from importlib import resources
+
+    return resources.files("adloop").joinpath("upload_card.html").read_text(encoding="utf-8")
+
+
+# App-only tools and the card that calls each one.
+_APP_ONLY_TOOLS = {
+    APPROVE_TOOL: "AdLoop approval card",
+    STORE_UPLOAD_TOOL: "AdLoop upload card",
+}
+
+
 class _AppOnlyToolsForCardClients(Middleware):
     """List and run app-only tools only for apps that render cards.
 
@@ -226,10 +254,11 @@ class _AppOnlyToolsForCardClients(Middleware):
         return [tool for tool in tools if not is_app_only(tool.meta)]
 
     async def on_call_tool(self, context, call_next):
-        if context.message.name == APPROVE_TOOL and not client_shows_cards():
+        card = _APP_ONLY_TOOLS.get(context.message.name)
+        if card and not client_shows_cards():
             from fastmcp.exceptions import ToolError
 
-            raise ToolError(f"{APPROVE_TOOL} can only be called from the AdLoop approval card.")
+            raise ToolError(f"{context.message.name} can only be called from the {card}.")
         return await call_next(context)
 
 
@@ -324,7 +353,7 @@ _API_DOCS: dict[str, str] = {
 
 
 # Write tools that do not produce a preview of their own.
-_NO_CARD_TOOLS = frozenset({"confirm_and_apply", APPROVE_TOOL})
+_NO_CARD_TOOLS = frozenset({"confirm_and_apply", APPROVE_TOOL, STORE_UPLOAD_TOOL})
 
 
 def _with_approval_card(fn: Callable) -> Callable:
@@ -3684,10 +3713,12 @@ def draft_image_assets(
     image_paths: _StrList = [],  # noqa: B006 — mutable default required for MCP JSON schema
     image_urls: _StrList = [],  # noqa: B006
     customer_id: str = "",
+    upload_ids: _StrList = [],  # noqa: B006
 ) -> dict:
-    """Draft campaign image assets from local files or public image URLs — returns a PREVIEW.
+    """Draft campaign image assets from local files, public image URLs or uploads — returns a PREVIEW.
 
-    At least one image in total is required across image_paths and image_urls.
+    At least one image in total is required across image_paths, image_urls
+    and upload_ids.
     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. Returns a preview with
@@ -3703,6 +3734,9 @@ def draft_image_assets(
             private, local or internal addresses are refused.
         customer_id: Google Ads customer ID (digits, dashes optional). Defaults to
             the configured account.
+        upload_ids: Ids of images the user uploaded (up_..., from
+            upload_images or list_uploads). The way to use an image that has
+            no public URL.
     """
     from adloop.ads.write import draft_image_assets as _impl
 
@@ -3712,6 +3746,7 @@ def draft_image_assets(
         campaign_id=campaign_id,
         image_paths=image_paths,
         image_urls=image_urls,
+        upload_ids=upload_ids,
     )
 
 
@@ -3988,6 +4023,94 @@ def approve_change(
         return _impl(config, plan_id=plan_id, dry_run=action == "test")
 
 
+# ---------------------------------------------------------------------------
+# Image uploads
+# ---------------------------------------------------------------------------
+# Images without a public URL reach AdLoop through the upload card (apps with
+# MCP Apps) or an upload link (hosted, every other app). Tools then take the
+# upload id: draft_image_assets(upload_ids=...), upload:<id> for Reddit.
+
+
+@_tool(
+    title="Upload images",
+    annotations=_READONLY,
+    tags={"core"},
+    meta={"ui": {"resourceUri": UPLOAD_CARD_URI}},
+)
+@_safe
+def upload_images() -> dict:
+    """Let the user upload images (PNG, JPEG, GIF up to 5 MB) for ad assets.
+
+    For images without a public URL, such as a file on the user's computer
+    or an image attached in the chat. An attached image cannot reach a tool,
+    so the user drops the same file on the card. Apps that show AdLoop's
+    cards display an upload card where the user drops the files; the card
+    then posts the upload ids into the chat. On AdLoop Cloud in other apps the result
+    carries an upload link for the user (or a coding agent, with curl).
+    Uploads expire after a day. The ids go into upload_ids of
+    draft_image_assets, or as "upload:<id>" into the image fields of
+    draft_reddit_ad. Returns the current uploads and how to add more.
+    """
+    from adloop.uploads import upload_instructions
+
+    return upload_instructions(client_shows_cards())
+
+
+@_tool(
+    title="Store an uploaded image",
+    annotations=_WRITE,
+    tags={"core"},
+    meta={"ui": {"resourceUri": UPLOAD_CARD_URI, "visibility": ["app"]}},
+)
+@_safe
+def store_image_upload(name: str, data_base64: str) -> dict:
+    """Store an image 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.
+
+    Args:
+        name: The file name, used for the asset name.
+        data_base64: The file content, base64-encoded.
+    """
+    import base64
+    import binascii
+
+    from adloop.uploads import UploadError, current_tenant, get_upload_store
+
+    try:
+        data = base64.b64decode(data_base64, validate=True)
+    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)
+    except UploadError as exc:
+        return {"error": f"{name}: {exc}"}
+    return {"status": "UPLOADED", **upload.summary()}
+
+
+@_tool(title="List uploaded images", annotations=_READONLY, tags={"core"})
+@_safe
+def list_uploads() -> dict:
+    """List the images 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.
+    """
+    from adloop.uploads import current_tenant, get_upload_store
+
+    uploads = [u.summary() for u in get_upload_store().list(current_tenant())]
+    return {
+        "uploads": uploads,
+        "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)."
+        ),
+    }
+
+
 # ---------------------------------------------------------------------------
 # Reddit Ads Tools
 # ---------------------------------------------------------------------------

adloop-0.26.1/src/adloop/upload_card.html

@@ -0,0 +1,247 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>AdLoop upload</title>
+<style>
+  :root { color-scheme: light dark; }
+  :root[data-theme="light"] { color-scheme: light; }
+  :root[data-theme="dark"] { color-scheme: dark; }
+  :root {
+    --bg: var(--color-background-primary, #ffffff);
+    --bg-2: var(--color-background-secondary, #f4f4f5);
+    --fg: var(--color-text-primary, #18181b);
+    --fg-2: var(--color-text-secondary, #52525b);
+    --border: var(--color-border-primary, #e4e4e7);
+    --accent: #2563eb;
+    --ok: var(--color-text-success, #15803d);
+    --ok-bg: var(--color-background-success, #f0fdf4);
+    --bad: var(--color-text-danger, #b91c1c);
+    --bad-bg: var(--color-background-danger, #fef2f2);
+    --radius: var(--border-radius-lg, 12px);
+    --font: var(--font-sans, ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif);
+    --mono: var(--font-mono, ui-monospace, SFMono-Regular, Menlo, monospace);
+  }
+  :root[data-theme="dark"] {
+    --bg: var(--color-background-primary, #18181b);
+    --bg-2: var(--color-background-secondary, #27272a);
+    --fg: var(--color-text-primary, #fafafa);
+    --fg-2: var(--color-text-secondary, #a1a1aa);
+    --border: var(--color-border-primary, #3f3f46);
+    --accent: #3b82f6;
+    --ok: var(--color-text-success, #4ade80);
+    --ok-bg: var(--color-background-success, #052e16);
+    --bad: var(--color-text-danger, #f87171);
+    --bad-bg: var(--color-background-danger, #2a0b0b);
+  }
+  * { box-sizing: border-box; }
+  html, body { margin: 0; background: transparent; }
+  body { font: 14px/1.45 var(--font); color: var(--fg); }
+  .card { background: var(--bg); border: 1px solid var(--border); border-radius: var(--radius); padding: 16px; }
+  .head { display: flex; align-items: center; gap: 8px; color: var(--fg-2); font-size: 12px; }
+  h1 { font-size: 16px; font-weight: 600; margin: 10px 0 2px; }
+  .sub { color: var(--fg-2); font-size: 12px; margin: 0 0 12px; }
+  .drop { display: flex; flex-direction: column; align-items: center; justify-content: center; gap: 6px; padding: 22px 12px; border: 1.5px dashed var(--border); border-radius: calc(var(--radius) - 4px); background: var(--bg-2); text-align: center; cursor: pointer; }
+  .drop.over { border-color: var(--accent); }
+  .drop small { color: var(--fg-2); font-size: 12px; }
+  .drop button { font: inherit; font-size: 13px; font-weight: 500; border-radius: 8px; padding: 6px 12px; border: 1px solid var(--accent); background: var(--accent); color: #fff; cursor: pointer; }
+  ul { list-style: none; margin: 12px 0 0; padding: 0; display: grid; gap: 6px; }
+  li { display: grid; grid-template-columns: 40px 1fr auto; gap: 10px; align-items: center; padding: 6px 8px; border-radius: 8px; background: var(--bg-2); }
+  li img, li .ph { width: 40px; height: 40px; object-fit: cover; border-radius: 6px; background: var(--border); }
+  li .name { overflow-wrap: anywhere; font-size: 13px; }
+  li .meta { color: var(--fg-2); font-size: 12px; font-family: var(--mono); }
+  li .state { font-size: 12px; }
+  li .state.ok { color: var(--ok); }
+  li .state.bad { color: var(--bad); }
+  .hidden { display: none !important; }
+</style>
+</head>
+<body>
+<div class="card">
+  <div class="head">
+    <svg width="18" height="18" viewBox="0 0 32 32" fill="none" aria-hidden="true"><rect width="32" height="32" rx="7" fill="#09090b"/><path d="M16 16 C 13.5 11.5, 6.5 11.5, 6.5 16 C 6.5 20.5, 13.5 20.5, 16 16 C 18.5 11.5, 25.5 11.5, 25.5 16 C 25.5 20.5, 18.5 20.5, 16 16 Z" stroke="#60a5fa" stroke-width="2.6" stroke-linejoin="round" stroke-linecap="round"/></svg>
+    <span data-t="brand">AdLoop · image upload</span>
+  </div>
+  <h1 data-t="title">Upload images for your ads</h1>
+  <p class="sub" data-t="sub">PNG, JPEG or GIF, up to 5 MB each. Uploads are kept for a day.</p>
+  <label class="drop" id="drop">
+    <span data-t="drop">Drop images here</span>
+    <small data-t="or">or</small>
+    <button type="button" id="pick" data-t="pick">Choose files</button>
+    <input type="file" id="file" accept="image/png,image/jpeg,image/gif" multiple class="hidden">
+  </label>
+  <ul id="list"></ul>
+</div>
+<script>
+(() => {
+  "use strict";
+  const TOOL = "store_image_upload";
+  const MAX_BYTES = 5120 * 1024;
+  const TYPES = ["image/png", "image/jpeg", "image/gif"];
+  const STRINGS = {
+    en: {
+      brand: "AdLoop · image upload", title: "Upload images for your ads",
+      sub: "PNG, JPEG or GIF, up to 5 MB each. Uploads are kept for a day.",
+      drop: "Drop images here", or: "or", pick: "Choose files",
+      uploading: "Uploading…", done: "Uploaded", tooBig: "Over 5 MB", wrongType: "Not PNG, JPEG or GIF",
+      message: "I uploaded images to AdLoop:\n{list}\nUse these upload ids for the ad.",
+    },
+    de: {
+      brand: "AdLoop · Bilder hochladen", title: "Bilder für deine Anzeigen hochladen",
+      sub: "PNG, JPEG oder GIF, bis 5 MB pro Bild. Uploads werden einen Tag aufbewahrt.",
+      drop: "Bilder hierher ziehen", or: "oder", pick: "Dateien auswählen",
+      uploading: "Wird hochgeladen…", done: "Hochgeladen", tooBig: "Größer als 5 MB", wrongType: "Kein PNG, JPEG oder GIF",
+      message: "Ich habe Bilder bei AdLoop hochgeladen:\n{list}\nNutze diese Upload-IDs für die Anzeige.",
+    },
+  };
+
+  let lang = "en";
+  document.documentElement.dataset.theme =
+    window.matchMedia && window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
+  let nextId = 1;
+  const pending = new Map();
+  const $ = (id) => document.getElementById(id);
+  const t = (key) => (STRINGS[lang] || STRINGS.en)[key] || STRINGS.en[key] || key;
+
+  function post(message) { window.parent.postMessage(message, "*"); }
+  function request(method, params) {
+    const id = nextId++;
+    post({ jsonrpc: "2.0", id, method, params });
+    return new Promise((resolve, reject) => pending.set(id, { resolve, reject }));
+  }
+  function notify(method, params) { post({ jsonrpc: "2.0", method, params }); }
+  function reportSize() {
+    const el = document.documentElement;
+    notify("ui/notifications/size-changed", { width: el.scrollWidth, height: el.scrollHeight });
+  }
+
+  function applyContext(ctx) {
+    if (!ctx) return;
+    if (ctx.theme === "dark" || ctx.theme === "light") document.documentElement.dataset.theme = ctx.theme;
+    const vars = ctx.styles && ctx.styles.variables;
+    if (vars) for (const [k, v] of Object.entries(vars)) if (v) document.documentElement.style.setProperty(k, v);
+    if (typeof ctx.locale === "string" && ctx.locale.toLowerCase().startsWith("de")) lang = "de";
+    for (const el of document.querySelectorAll("[data-t]")) el.textContent = t(el.dataset.t);
+  }
+
+  function payloadOf(result) {
+    if (!result) return {};
+    if (result.structuredContent && typeof result.structuredContent === "object") return result.structuredContent;
+    const text = (result.content || []).filter((c) => c && c.type === "text").map((c) => c.text).join("");
+    try { return JSON.parse(text); } catch (_) { return { error: text }; }
+  }
+
+  function addRow(name, src) {
+    const li = document.createElement("li");
+    const img = document.createElement(src ? "img" : "div");
+    if (src) { img.src = src; img.alt = ""; } else { img.className = "ph"; }
+    const info = document.createElement("div");
+    const n = document.createElement("div"); n.className = "name"; n.textContent = name;
+    const m = document.createElement("div"); m.className = "meta";
+    info.append(n, m);
+    const state = document.createElement("span"); state.className = "state";
+    li.append(img, info, state);
+    $("list").append(li);
+    reportSize();
+    return { meta: m, state };
+  }
+
+  function describe(u) {
+    return u.upload_id + " · " + u.width + "×" + u.height + " · " + u.size_kb + " KB";
+  }
+
+  function readBase64(file) {
+    return new Promise((resolve, reject) => {
+      const reader = new FileReader();
+      reader.onload = () => resolve(String(reader.result).split(",", 2)[1] || "");
+      reader.onerror = () => reject(reader.error || new Error("read failed"));
+      reader.readAsDataURL(file);
+    });
+  }
+
+  async function upload(files) {
+    const stored = [];
+    for (const file of files) {
+      const row = addRow(file.name, TYPES.includes(file.type) ? URL.createObjectURL(file) : "");
+      if (!TYPES.includes(file.type)) { row.state.textContent = t("wrongType"); row.state.classList.add("bad"); continue; }
+      if (file.size > MAX_BYTES) { row.state.textContent = t("tooBig"); row.state.classList.add("bad"); continue; }
+      row.state.textContent = t("uploading");
+      try {
+        const result = await request("tools/call", { name: TOOL, arguments: { name: file.name, data_base64: await readBase64(file) } });
+        const r = payloadOf(result);
+        if ((result && result.isError) || r.error || !r.upload_id) throw new Error(r.error || "upload failed");
+        row.meta.textContent = describe(r);
+        row.state.textContent = t("done");
+        row.state.classList.add("ok");
+        stored.push(r);
+      } catch (err) {
+        row.state.textContent = err && err.message ? err.message : String(err);
+        row.state.classList.add("bad");
+      }
+      reportSize();
+    }
+    if (stored.length) {
+      const list = stored.map((u) => "- " + u.name + ": " + describe(u)).join("\n");
+      request("ui/message", { role: "user", content: { type: "text", text: t("message").replace("{list}", list) } }).catch(() => {});
+    }
+  }
+
+  const drop = $("drop");
+  $("pick").addEventListener("click", (e) => { e.preventDefault(); $("file").click(); });
+  $("file").addEventListener("change", () => { upload(Array.from($("file").files || [])); $("file").value = ""; });
+  drop.addEventListener("dragover", (e) => { e.preventDefault(); drop.classList.add("over"); });
+  drop.addEventListener("dragleave", () => drop.classList.remove("over"));
+  drop.addEventListener("drop", (e) => {
+    e.preventDefault();
+    drop.classList.remove("over");
+    upload(Array.from((e.dataTransfer && e.dataTransfer.files) || []));
+  });
+
+  let shownExisting = false;
+  function onToolResult(result) {
+    if (shownExisting || !result) return;
+    shownExisting = true;
+    const r = payloadOf(result);
+    for (const u of r.uploads || []) {
+      const row = addRow(u.name, "");
+      row.meta.textContent = describe(u);
+      row.state.textContent = t("done");
+      row.state.classList.add("ok");
+    }
+  }
+
+  window.addEventListener("message", (event) => {
+    if (event.source !== window.parent) return;
+    const msg = event.data;
+    if (!msg || msg.jsonrpc !== "2.0") return;
+    if (msg.id !== undefined && pending.has(msg.id) && !msg.method) {
+      const { resolve, reject } = pending.get(msg.id);
+      pending.delete(msg.id);
+      if (msg.error) reject(new Error(msg.error.message || "error")); else resolve(msg.result);
+      return;
+    }
+    switch (msg.method) {
+      case "ui/notifications/tool-result": onToolResult(msg.params); break;
+      case "ui/notifications/host-context-changed": applyContext(msg.params); break;
+      case "ui/resource-teardown": post({ jsonrpc: "2.0", id: msg.id, result: {} }); break;
+      case "ping": post({ jsonrpc: "2.0", id: msg.id, result: {} }); break;
+      default:
+        if (msg.id !== undefined && msg.method) post({ jsonrpc: "2.0", id: msg.id, error: { code: -32601, message: "Method not found" } });
+    }
+  });
+
+  new ResizeObserver(reportSize).observe(document.documentElement);
+  request("ui/initialize", {
+    protocolVersion: "2026-01-26",
+    appCapabilities: { availableDisplayModes: ["inline"] },
+    clientInfo: { name: "AdLoop upload card", version: "1" },
+  }).then((result) => {
+    applyContext(result && result.hostContext);
+    notify("ui/notifications/initialized", {});
+    reportSize();
+  }).catch(() => notify("ui/notifications/initialized", {}));
+})();
+</script>
+</body>
+</html>

adloop-0.26.1/src/adloop/uploads.py

@@ -0,0 +1,286 @@
+"""Image uploads: files a user hands to AdLoop without a public URL.
+
+AI apps cannot pass a file from the chat to a tool, so an upload reaches
+AdLoop on its own path: the upload card (MCP Apps) calls the app-only
+``store_image_upload`` tool with the file, or, on a hosted server, the user
+opens a one-time upload link. Either way the image lands in an
+:class:`UploadStore` under an ``up_...`` id, and the tools take that id:
+``draft_image_assets(upload_ids=[...])`` for Google Ads, ``upload:<id>`` in
+the media fields of ``draft_reddit_ad``.
+
+Uploads are short-lived: they expire after a day and exist to be turned
+into ad assets, not to be kept. Self-hosted, the store is a folder under
+``~/.adloop/uploads``. A hosted runtime sets its own store and the links
+(:func:`set_upload_links`): the upload page and the short-lived public file
+link Reddit downloads from.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+import secrets
+import time
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Protocol
+
+UPLOAD_PREFIX = "upload:"
+UPLOAD_CARD_URI = "ui://adloop/upload-card.html"
+STORE_UPLOAD_TOOL = "store_image_upload"
+MAX_UPLOAD_BYTES = 5120 * 1024  # Google's image asset limit; Reddit takes more
+DEFAULT_TTL_SECONDS = 24 * 3600
+MAX_FILES_PER_TENANT = 50
+MAX_BYTES_PER_TENANT = 100 * 1024 * 1024
+_ID_PATTERN = re.compile(r"^up_[A-Za-z0-9_-]{8,40}$")
+
+
+@dataclass(frozen=True)
+class Upload:
+    upload_id: str
+    name: str
+    mime_type: str
+    width: int
+    height: int
+    size_bytes: int
+    sha256: str
+    created_at: float
+    expires_at: float
+
+    def summary(self) -> dict:
+        return {
+            "upload_id": self.upload_id,
+            "name": self.name,
+            "mime_type": self.mime_type,
+            "width": self.width,
+            "height": self.height,
+            "size_kb": round(self.size_bytes / 1024, 1),
+            "expires_in_hours": max(0, round((self.expires_at - time.time()) / 3600, 1)),
+        }
+
+
+class UploadError(ValueError):
+    """An upload was refused or cannot be found; the message says why."""
+
+
+class UploadLinks(Protocol):
+    def upload_page(self, tenant: str) -> tuple[str, int]:
+        """A URL where the user uploads files for ``tenant``, and its lifetime in seconds."""
+
+    def public_file(self, tenant: str, upload_id: str) -> str:
+        """A short-lived public URL serving the upload (for Reddit to download)."""
+
+
+def _clean_name(name: str) -> str:
+    base = os.path.basename(str(name or "").replace("\\", "/")).strip()
+    base = re.sub(r"[\x00-\x1f]", "", base)
+    return base[:120] or "image"
+
+
+def inspect_image(data: bytes) -> tuple[str, int, int]:
+    """(mime_type, width, height) of a PNG, JPEG or GIF; raises UploadError otherwise."""
+    from adloop.ads.write import _detect_image_type_and_size
+
+    if not data:
+        raise UploadError("the file is empty")
+    if len(data) > MAX_UPLOAD_BYTES:
+        raise UploadError(
+            f"the file is {len(data) / 1024:.0f} KB; images can be at most {MAX_UPLOAD_BYTES // 1024} KB"
+        )
+    try:
+        return _detect_image_type_and_size(data)
+    except ValueError as exc:
+        raise UploadError(f"not a usable image: {exc} (PNG, JPEG or GIF)") from exc
+
+
+class LocalUploadStore:
+    """Uploads as files in a folder, one subfolder per tenant.
+
+    Expired files are removed whenever the store is used; there is no timer.
+    """
+
+    def __init__(
+        self,
+        root: str | Path,
+        *,
+        ttl_seconds: int = DEFAULT_TTL_SECONDS,
+        max_files: int = MAX_FILES_PER_TENANT,
+        max_bytes: int = MAX_BYTES_PER_TENANT,
+    ) -> None:
+        self.root = Path(root)
+        self.ttl_seconds = ttl_seconds
+        self.max_files = max_files
+        self.max_bytes = max_bytes
+
+    def _dir(self, tenant: str) -> Path:
+        key = hashlib.sha256(str(tenant or "local").encode()).hexdigest()[:24]
+        return self.root / key
+
+    def _entries(self, tenant: str) -> list[Upload]:
+        folder = self._dir(tenant)
+        if not folder.is_dir():
+            return []
+        now = time.time()
+        uploads: list[Upload] = []
+        for meta_path in folder.glob("up_*.json"):
+            try:
+                upload = Upload(**json.loads(meta_path.read_text()))
+            except (OSError, ValueError, TypeError):
+                continue
+            if upload.expires_at <= now:
+                self._remove(folder, upload.upload_id)
+                continue
+            uploads.append(upload)
+        return sorted(uploads, key=lambda u: u.created_at)
+
+    @staticmethod
+    def _remove(folder: Path, upload_id: str) -> None:
+        for suffix in (".bin", ".json"):
+            try:
+                (folder / f"{upload_id}{suffix}").unlink()
+            except FileNotFoundError:
+                pass
+
+    def put(self, tenant: str, name: str, data: bytes) -> Upload:
+        mime_type, width, height = inspect_image(data)
+        existing = self._entries(tenant)
+        digest = hashlib.sha256(data).hexdigest()
+        for upload in existing:
+            if upload.sha256 == digest:
+                return upload  # the same image twice is one upload
+        if len(existing) >= self.max_files:
+            raise UploadError(
+                f"this workspace already holds {len(existing)} uploads; they expire after a day"
+            )
+        if sum(u.size_bytes for u in existing) + len(data) > self.max_bytes:
+            raise UploadError(
+                f"uploads are limited to {self.max_bytes // (1024 * 1024)} MB per workspace; "
+                "they expire after a day"
+            )
+        now = time.time()
+        upload = Upload(
+            upload_id="up_" + secrets.token_urlsafe(12),
+            name=_clean_name(name),
+            mime_type=mime_type,
+            width=width,
+            height=height,
+            size_bytes=len(data),
+            sha256=digest,
+            created_at=now,
+            expires_at=now + self.ttl_seconds,
+        )
+        folder = self._dir(tenant)
+        folder.mkdir(parents=True, exist_ok=True)
+        for suffix, payload in ((".bin", data), (".json", json.dumps(asdict(upload)).encode())):
+            tmp = folder / f".{upload.upload_id}{suffix}.tmp"
+            tmp.write_bytes(payload)
+            os.replace(tmp, folder / f"{upload.upload_id}{suffix}")
+        return upload
+
+    def get(self, tenant: str, upload_id: str) -> tuple[Upload, bytes]:
+        upload_id = str(upload_id or "").strip()
+        if not _ID_PATTERN.match(upload_id):
+            raise UploadError(f"'{upload_id}' is not an upload id (they look like up_...)")
+        for upload in self._entries(tenant):
+            if upload.upload_id == upload_id:
+                data = (self._dir(tenant) / f"{upload_id}.bin").read_bytes()
+                return upload, data
+        raise UploadError(
+            f"upload {upload_id} was not found; uploads expire after a day (see list_uploads)"
+        )
+
+    def list(self, tenant: str) -> list[Upload]:
+        return self._entries(tenant)
+
+
+_store: LocalUploadStore | None = None
+_links: UploadLinks | None = None
+
+
+def set_upload_store(store: LocalUploadStore | None) -> None:
+    global _store
+    _store = store
+
+
+def get_upload_store() -> LocalUploadStore:
+    global _store
+    if _store is None:
+        _store = LocalUploadStore(Path.home() / ".adloop" / "uploads")
+    return _store
+
+
+def set_upload_links(links: UploadLinks | None) -> None:
+    """Hosted runtimes: where users upload, and how Reddit downloads uploads."""
+    global _links
+    _links = links
+
+
+def get_upload_links() -> UploadLinks | None:
+    return _links
+
+
+def current_tenant() -> str:
+    from adloop.runtime import current_tenant as _tenant
+
+    return _tenant() or ""
+
+
+def upload_ref(value: str) -> str | None:
+    """The upload id in an ``upload:<id>`` reference, else None."""
+    text = str(value or "").strip()
+    if text.lower().startswith(UPLOAD_PREFIX):
+        return text[len(UPLOAD_PREFIX):].strip()
+    return None
+
+
+def public_url_for(upload_id: str) -> str:
+    """A URL Reddit can download the upload from; raises UploadError without one."""
+    links = get_upload_links()
+    if links is None:
+        raise UploadError(
+            "upload: references need a public link Reddit can download, which only AdLoop "
+            "Cloud provides. Self-hosted, pass a public image URL instead."
+        )
+    get_upload_store().get(current_tenant(), upload_id)  # exists and not expired
+    return links.public_file(current_tenant(), upload_id)
+
+
+def upload_instructions(shows_cards: bool) -> dict:
+    """What ``upload_images`` returns: current uploads plus the way to add more."""
+    tenant = current_tenant()
+    result: dict = {"uploads": [u.summary() for u in get_upload_store().list(tenant)]}
+    use = (
+        "Use the ids as upload_ids in draft_image_assets, or as \"upload:<upload_id>\" in "
+        "the image fields of draft_reddit_ad."
+    )
+    if shows_cards:
+        result["upload"] = "card"
+        result["instructions"] = (
+            "The user sees an AdLoop upload card and drops the images there. The card posts "
+            "the upload ids into the chat when it is done; wait for that. " + use
+        )
+        return result
+    links = get_upload_links()
+    if links is None:
+        result["instructions"] = (
+            "This app shows no upload card. Self-hosted, pass the files directly: "
+            "draft_image_assets(image_paths=[...]) takes local files; Reddit ads need a "
+            "public image URL."
+        )
+        return result
+    url, lifetime = links.upload_page(tenant)
+    minutes = max(1, lifetime // 60)
+    result.update({
+        "upload_url": url,
+        "expires_in_minutes": minutes,
+        "curl_example": f'curl -T "logo.png" "{url}/"',
+        "instructions": (
+            f"Give the user this upload link (valid {minutes} minutes): they open it in the "
+            "browser and drop the images, then tell you they are done; call list_uploads for "
+            "the ids. A coding agent with the files on disk can upload them itself with curl "
+            "(curl_example; one call per file). " + use
+        ),
+    })
+    return result