adloop 0.22.2__tar.gz → 0.23.0__tar.gz

{adloop-0.22.2 → adloop-0.23.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: adloop
-Version: 0.22.2
+Version: 0.23.0
 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
@@ -81,7 +81,7 @@ AdLoop exists because managing Google Ads alongside your code is a mess. These a
 
 - **"Is my tracking even working?"** Compare the event names in your actual codebase against what GA4 is receiving. Find the mismatches: events you fire that GA4 never sees, events GA4 records that you didn't know about.
 
-- **"I need to create ads but the Google Ads UI is hostile."** Draft responsive search ads, create campaigns, add keywords — all through natural language. Every change shows a preview first. Nothing goes live without your explicit confirmation. New ads and campaigns start paused.
+- **"I need to create ads but the Google Ads UI is hostile."** Draft responsive search ads, create campaigns, add keywords — all through natural language. Every change shows a preview first. Nothing goes live without your explicit confirmation: in Claude, ChatGPT and VS Code the preview is an approval card, and only your click on Apply changes the account (the AI cannot press it). New ads and campaigns start paused.
 
 - **"My landing page gets paid traffic but nobody converts."** AdLoop joins your ad final URLs with GA4 page-level data. See which pages get clicks but no conversions, which have high bounce rates, and which ones are orphaned from any ad campaign.
 

{adloop-0.22.2 → adloop-0.23.0}/README.md

@@ -53,7 +53,7 @@ AdLoop exists because managing Google Ads alongside your code is a mess. These a
 
 - **"Is my tracking even working?"** Compare the event names in your actual codebase against what GA4 is receiving. Find the mismatches: events you fire that GA4 never sees, events GA4 records that you didn't know about.
 
-- **"I need to create ads but the Google Ads UI is hostile."** Draft responsive search ads, create campaigns, add keywords — all through natural language. Every change shows a preview first. Nothing goes live without your explicit confirmation. New ads and campaigns start paused.
+- **"I need to create ads but the Google Ads UI is hostile."** Draft responsive search ads, create campaigns, add keywords — all through natural language. Every change shows a preview first. Nothing goes live without your explicit confirmation: in Claude, ChatGPT and VS Code the preview is an approval card, and only your click on Apply changes the account (the AI cannot press it). New ads and campaigns start paused.
 
 - **"My landing page gets paid traffic but nobody converts."** AdLoop joins your ad final URLs with GA4 page-level data. See which pages get clicks but no conversions, which have high bounce rates, and which ones are orphaned from any ad campaign.
 

{adloop-0.22.2 → adloop-0.23.0}/pyproject.toml

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

{adloop-0.22.2 → adloop-0.23.0}/pyproject.toml.orig

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

{adloop-0.22.2 → adloop-0.23.0}/src/adloop/config.py

@@ -87,6 +87,12 @@ class SafetyConfig:
     # (which blocks real writes entirely), this only enforces the order:
     # preview first, apply second.
     two_phase_apply: bool = False
+    # Approval cards: when the AI app shows AdLoop's approval card (MCP
+    # Apps), only a click on the card applies a change, and
+    # confirm_and_apply(dry_run=false) from the model is refused. True also
+    # accepts the approval in chat, for app surfaces that claim card support
+    # but do not render it. Apps without cards always use the chat flow.
+    allow_chat_approval: bool = False
     log_file: str = "~/.adloop/audit.log"
     blocked_operations: list[str] = field(default_factory=list)
 
@@ -217,6 +223,7 @@ def load_config(config_path: str | None = None) -> AdLoopConfig:
             max_bid_increase_pct=safety_raw.get("max_bid_increase_pct", 100),
             require_dry_run=safety_raw.get("require_dry_run", True),
             two_phase_apply=safety_raw.get("two_phase_apply", False),
+            allow_chat_approval=safety_raw.get("allow_chat_approval", False),
             log_file=_text(safety_raw, "log_file", "~/.adloop/audit.log"),
             blocked_operations=safety_raw.get("blocked_operations", []),
         ),

{adloop-0.22.2 → adloop-0.23.0}/src/adloop/rules/adloop.md

@@ -296,6 +296,8 @@ Same draft → preview → `confirm_and_apply` gate; the plan carries `platform:
 3. Call `confirm_and_apply(plan_id=..., dry_run=true)` first to test
 4. Only call with `dry_run=false` after explicit user confirmation
 
+**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). Apps without cards 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.
 - `draft_campaign` REQUIRES `geo_target_ids` and `language_ids` — campaigns without targeting waste budget. The tool rejects drafts with missing targeting.

adloop-0.23.0/src/adloop/safety/approval.py

@@ -0,0 +1,191 @@
+"""Approval cards: a change preview that only a human click applies.
+
+AI apps that support MCP Apps (the ``io.modelcontextprotocol/ui``
+extension) render every write tool's preview as AdLoop's approval card,
+with "Test run" and "Apply" buttons. The buttons call ``approve_change``,
+an app-only tool: the MCP Apps spec requires the app to keep it out of the
+model's tool list, AdLoop lists and runs it only for card-capable clients,
+and every call needs the plan's approval code. That code travels in the
+preview result's ``_meta``, which goes to the card and is not meant for the
+model's context, and it is an HMAC the model cannot compute.
+
+While a card can be shown, ``confirm_and_apply(dry_run=false)`` from the
+model is refused unless ``safety.allow_chat_approval`` is on, so "the user
+said yes" in the chat is not enough to change an account. Clients without
+the extension keep the chat flow unchanged.
+"""
+
+from __future__ import annotations
+
+import contextvars
+import hashlib
+import hmac
+import json
+import secrets
+from collections.abc import Iterator
+from contextlib import contextmanager
+from functools import lru_cache
+from importlib import resources
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from adloop.safety.preview import ChangePlan
+
+UI_EXTENSION_ID = "io.modelcontextprotocol/ui"
+CARD_URI = "ui://adloop/approval-card.html"
+CARD_MIME_TYPE = "text/html;profile=mcp-app"
+META_KEY = "adloop/approval"
+APPROVE_TOOL = "approve_change"
+
+_secret: bytes = secrets.token_bytes(32)
+_card_click: contextvars.ContextVar[bool] = contextvars.ContextVar(
+    "adloop_card_click", default=False
+)
+
+
+def set_approval_secret(secret: bytes) -> None:
+    """Key the approval codes.
+
+    Self-hosted, plans live in memory, so a random key per process is
+    enough. A hosted runtime keeps plans across restarts and workers and
+    sets a stable key derived from its own secrets.
+    """
+    global _secret
+    if len(secret) < 32:
+        raise ValueError("approval secret must be at least 32 bytes")
+    _secret = bytes(secret)
+
+
+def client_shows_cards() -> bool:
+    """Whether the calling AI app declared MCP Apps support.
+
+    Read per request: on the 2026-07-28 protocol the capabilities ride every
+    request, so this also works on a stateless server. Anything that cannot
+    be read counts as "no cards", which keeps the chat flow.
+    """
+    try:
+        from fastmcp.server.dependencies import get_context
+
+        return bool(get_context().client_supports_extension(UI_EXTENSION_ID))
+    except Exception:
+        return False
+
+
+def approval_code(plan: ChangePlan) -> str:
+    """The code the card must present to run or apply ``plan``."""
+    from adloop.runtime import current_tenant
+
+    message = "\x00".join((current_tenant(), plan.plan_id, plan.created_at))
+    return hmac.new(_secret, message.encode(), hashlib.sha256).hexdigest()[:32]
+
+
+def code_matches(plan: ChangePlan, code: str) -> bool:
+    return hmac.compare_digest(approval_code(plan), str(code or ""))
+
+
+def card_click_active() -> bool:
+    """True while ``approve_change`` runs a click from the card."""
+    return _card_click.get()
+
+
+@contextmanager
+def card_click() -> Iterator[None]:
+    token = _card_click.set(True)
+    try:
+        yield
+    finally:
+        _card_click.reset(token)
+
+
+def chat_apply_refusal(plan_id: str) -> dict | None:
+    """The refusal for a model-issued real apply, or None when it may run."""
+    from adloop.runtime import current_config
+
+    if card_click_active() or not client_shows_cards():
+        return None
+    if current_config().safety.allow_chat_approval:
+        return None
+    return {
+        "status": "APPROVE_ON_CARD",
+        "plan_id": plan_id,
+        "message": (
+            "Nothing was changed. In this app, changes are applied only by the "
+            "user's click on the AdLoop approval card shown with the preview "
+            "(Test run, then Apply). Ask the user to approve it there; do not "
+            "retry confirm_and_apply with dry_run=false. If the card is not "
+            "visible in their app, the workspace owner can allow approval in "
+            "chat (AdLoop Cloud: Settings → Safety; self-hosted: "
+            "safety.allow_chat_approval in the config)."
+        ),
+    }
+
+
+def _instructions(plan_id: str) -> str:
+    from adloop.runtime import current_config
+
+    text = (
+        "The user sees this preview as an AdLoop approval card with Test run "
+        "and Apply buttons, and approves it there. Summarize the change and "
+        "any warnings, then let the user decide on the card."
+    )
+    if current_config().safety.allow_chat_approval:
+        return text + (
+            " Approval in chat is also allowed: only if the user explicitly "
+            f"says so, call confirm_and_apply with plan_id='{plan_id}'."
+        )
+    return text + (
+        " Do not call confirm_and_apply with dry_run=false: in this app it "
+        "is refused, only the click applies. A dry run "
+        f"(confirm_and_apply plan_id='{plan_id}', dry_run=true) is allowed."
+    )
+
+
+def with_card(result: Any) -> Any:
+    """Return a write tool's preview as a card result for card-capable apps.
+
+    Anything that is not a pending preview (errors, refusals, notes) and
+    every result for an app without cards passes through unchanged.
+    """
+    if not isinstance(result, dict) or result.get("status") != "PENDING_CONFIRMATION":
+        return result
+    if not client_shows_cards():
+        return result
+    from adloop.safety.preview import get_plan
+
+    plan = get_plan(str(result.get("plan_id") or ""))
+    if plan is None:
+        return result
+
+    from fastmcp.tools import ToolResult
+    from mcp.types import TextContent
+
+    preview = {**result, "approval": "card", "instructions": _instructions(plan.plan_id)}
+    return ToolResult(
+        content=[TextContent(type="text", text=json.dumps(preview, default=str))],
+        structured_content=preview,
+        meta={
+            META_KEY: {
+                "plan_id": plan.plan_id,
+                "code": approval_code(plan),
+                "tool": APPROVE_TOOL,
+            }
+        },
+    )
+
+
+@lru_cache(maxsize=1)
+def card_html() -> str:
+    return (
+        resources.files("adloop.safety")
+        .joinpath("approval_card.html")
+        .read_text(encoding="utf-8")
+    )
+
+
+def is_app_only(meta: dict | None) -> bool:
+    """True for tools the MCP Apps spec keeps out of the model's tool list."""
+    ui = (meta or {}).get("ui")
+    if not isinstance(ui, dict):
+        return False
+    visibility = ui.get("visibility")
+    return isinstance(visibility, list) and "model" not in visibility

adloop-0.23.0/src/adloop/safety/approval_card.html

@@ -0,0 +1,360 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>AdLoop approval</title>
+<style>
+  /* Hosts may send their colours as light-dark() values, which resolve by
+     color-scheme; the script sets it from the host theme. */
+  :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;
+    --accent-fg: #ffffff;
+    --ok: var(--color-text-success, #15803d);
+    --ok-bg: var(--color-background-success, #f0fdf4);
+    --warn: var(--color-text-warning, #a16207);
+    --warn-bg: var(--color-background-warning, #fefce8);
+    --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);
+    --warn: var(--color-text-warning, #facc15);
+    --warn-bg: var(--color-background-warning, #2a2205);
+    --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; }
+  .hidden { display: none !important; }
+  .head { display: flex; align-items: center; gap: 8px; color: var(--fg-2); font-size: 12px; }
+  .head svg { flex: none; }
+  .badge { margin-left: auto; border: 1px solid var(--border); border-radius: 999px; padding: 1px 8px; font-size: 11px; }
+  h1 { font-size: 16px; font-weight: 600; margin: 10px 0 2px; }
+  .sub { color: var(--fg-2); font-size: 12px; margin: 0 0 12px; overflow-wrap: anywhere; }
+  dl { display: grid; grid-template-columns: minmax(90px, max-content) 1fr; gap: 6px 12px; margin: 0; padding: 12px; background: var(--bg-2); border-radius: calc(var(--radius) - 4px); }
+  dt { color: var(--fg-2); font-size: 12px; overflow-wrap: anywhere; }
+  dd { margin: 0; overflow-wrap: anywhere; white-space: pre-wrap; }
+  dd.mono { font: 12px/1.4 var(--mono); }
+  .more { grid-column: 1 / -1; color: var(--fg-2); font-size: 12px; }
+  .note { margin-top: 10px; padding: 8px 10px; border-radius: 8px; font-size: 13px; overflow-wrap: anywhere; }
+  .note.warn { color: var(--warn); background: var(--warn-bg); }
+  .note.ok { color: var(--ok); background: var(--ok-bg); }
+  .note.bad { color: var(--bad); background: var(--bad-bg); }
+  .note.info { color: var(--fg-2); background: var(--bg-2); }
+  label.ack { display: flex; gap: 8px; align-items: flex-start; margin-top: 12px; font-size: 13px; }
+  .actions { display: flex; gap: 8px; justify-content: flex-end; margin-top: 14px; flex-wrap: wrap; }
+  button { font: inherit; font-size: 13px; font-weight: 500; border-radius: 8px; padding: 7px 14px; cursor: pointer; border: 1px solid var(--border); background: transparent; color: var(--fg); }
+  button.primary { background: var(--accent); border-color: var(--accent); color: var(--accent-fg); }
+  button.danger { background: var(--bad); border-color: var(--bad); color: #fff; }
+  button:disabled { opacity: .45; cursor: default; }
+  .steps { display: flex; gap: 6px; margin-top: 12px; font-size: 12px; color: var(--fg-2); }
+  .steps span.done { color: var(--ok); }
+</style>
+</head>
+<body>
+<div class="card hidden" id="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 · approval required</span>
+    <span class="badge" id="platform"></span>
+  </div>
+  <h1 id="title"></h1>
+  <p class="sub" id="subtitle"></p>
+  <dl id="changes"></dl>
+  <div id="warnings"></div>
+  <label class="ack hidden" id="ackRow"><input type="checkbox" id="ack"> <span data-t="ack">I understand that this cannot be undone.</span></label>
+  <div class="steps"><span id="stepTest" data-t="stepTest">1 · Test run</span><span>→</span><span id="stepApply" data-t="stepApply">2 · Apply</span></div>
+  <div id="status"></div>
+  <div class="actions" id="actions">
+    <button id="discard" data-t="discard">Discard</button>
+    <button id="test" class="primary" data-t="test">Test run</button>
+    <button id="apply" class="primary hidden" data-t="apply">Apply</button>
+  </div>
+</div>
+<script>
+(() => {
+  "use strict";
+  const META_KEY = "adloop/approval";
+  const STRINGS = {
+    en: {
+      brand: "AdLoop · approval required", ack: "I understand that this cannot be undone.",
+      stepTest: "1 · Test run", stepApply: "2 · Apply", discard: "Discard", test: "Test run", apply: "Apply",
+      running: "Running the test…", applying: "Applying…",
+      testOk: "Test run passed. Nothing was changed yet. Apply makes the change live.",
+      testForced: "Live changes are switched off, so only test runs are possible.",
+      applied: "Applied.", discarded: "Discarded. Nothing was changed.",
+      failed: "Not applied:", more: "more fields not shown",
+      msgApplied: "Applied on the AdLoop approval card: {op} (plan {id}).",
+      msgDiscarded: "Discarded on the AdLoop approval card: {op} (plan {id}). Nothing was changed.",
+      gone: "This change is no longer pending (applied, discarded or expired).",
+    },
+    de: {
+      brand: "AdLoop · Freigabe nötig", ack: "Mir ist klar, dass sich das nicht rückgängig machen lässt.",
+      stepTest: "1 · Testlauf", stepApply: "2 · Anwenden", discard: "Verwerfen", test: "Testlauf", apply: "Anwenden",
+      running: "Testlauf läuft…", applying: "Wird angewendet…",
+      testOk: "Testlauf bestanden. Noch ist nichts geändert. Anwenden macht die Änderung live.",
+      testForced: "Echte Änderungen sind ausgeschaltet, daher sind nur Testläufe möglich.",
+      applied: "Angewendet.", discarded: "Verworfen. Nichts wurde geändert.",
+      failed: "Nicht angewendet:", more: "weitere Felder nicht angezeigt",
+      msgApplied: "Auf der AdLoop-Freigabekarte angewendet: {op} (Plan {id}).",
+      msgDiscarded: "Auf der AdLoop-Freigabekarte verworfen: {op} (Plan {id}). Nichts wurde geändert.",
+      gone: "Diese Änderung ist nicht mehr offen (angewendet, verworfen oder abgelaufen).",
+    },
+  };
+  const PLATFORMS = { google: "Google Ads", reddit: "Reddit Ads", ga4: "Google Analytics", gtm: "Tag Manager" };
+  const MAX_ROWS = 14;
+
+  let lang = "en";
+  // Until the host says otherwise, follow the system theme.
+  document.documentElement.dataset.theme =
+    window.matchMedia && window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
+  let nextId = 1;
+  const pending = new Map();
+  let plan = null; // { planId, code, tool, preview }
+  let busy = false;
+
+  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 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 reportSize() {
+    const el = document.documentElement;
+    notify("ui/notifications/size-changed", { width: el.scrollWidth, height: el.scrollHeight });
+  }
+
+  function humanize(op) {
+    const s = String(op || "change").replace(/^(reddit|gtm|ga4)_/, "").replace(/_/g, " ");
+    return s.charAt(0).toUpperCase() + s.slice(1);
+  }
+
+  function platformOf(preview) {
+    const op = String(preview.operation || "");
+    if (preview.platform === "reddit" || op.startsWith("reddit_")) return "reddit";
+    if (op.startsWith("gtm_")) return "gtm";
+    if (op.includes("key_event")) return "ga4";
+    return "google";
+  }
+
+  function formatValue(value) {
+    if (value === null || value === undefined) return { text: "–", mono: false };
+    if (typeof value === "boolean") return { text: value ? "✓" : "✗", mono: false };
+    if (typeof value !== "object") return { text: String(value), mono: false };
+    if (Array.isArray(value) && value.every((v) => typeof v !== "object" || v === null)) {
+      return { text: value.map(String).join("\n"), mono: false };
+    }
+    return { text: JSON.stringify(value, null, 2), mono: true };
+  }
+
+  function row(dl, key, value) {
+    const dt = document.createElement("dt");
+    dt.textContent = String(key).replace(/_/g, " ");
+    const dd = document.createElement("dd");
+    const v = formatValue(value);
+    dd.textContent = v.text;
+    if (v.mono) dd.classList.add("mono");
+    dl.append(dt, dd);
+  }
+
+  function note(container, kind, text) {
+    const div = document.createElement("div");
+    div.className = "note " + kind;
+    div.textContent = text;
+    container.append(div);
+  }
+
+  function render() {
+    const p = plan.preview;
+    $("platform").textContent = PLATFORMS[platformOf(p)];
+    $("title").textContent = humanize(p.operation);
+    const sub = [];
+    if (p.entity_type) sub.push(String(p.entity_type).replace(/_/g, " ") + (p.entity_id ? " " + p.entity_id : ""));
+    if (p.customer_id) sub.push(String(p.customer_id));
+    sub.push("plan " + plan.planId);
+    $("subtitle").textContent = sub.join(" · ");
+
+    const dl = $("changes");
+    dl.replaceChildren();
+    const entries = Object.entries(p.changes || {});
+    entries.slice(0, MAX_ROWS).forEach(([k, v]) => row(dl, k, v));
+    if (entries.length > MAX_ROWS) {
+      const more = document.createElement("div");
+      more.className = "more";
+      more.textContent = (entries.length - MAX_ROWS) + " " + t("more");
+      dl.append(more);
+    }
+    if (!entries.length) dl.classList.add("hidden");
+
+    const warnings = $("warnings");
+    warnings.replaceChildren();
+    const list = [].concat(p.warnings || [], (p.changes && p.changes.warnings) || []);
+    for (const w of list) note(warnings, "warn", typeof w === "string" ? w : JSON.stringify(w));
+
+    $("ackRow").classList.toggle("hidden", !p.requires_double_confirm);
+    $("card").classList.remove("hidden");
+    updateButtons();
+  }
+
+  let tested = false;
+  let finished = false;
+  function updateButtons() {
+    const needsAck = plan.preview.requires_double_confirm && !$("ack").checked;
+    $("test").classList.toggle("hidden", tested || finished);
+    $("apply").classList.toggle("hidden", !tested || finished);
+    $("apply").classList.toggle("danger", !!plan.preview.requires_double_confirm);
+    $("apply").classList.toggle("primary", !plan.preview.requires_double_confirm);
+    $("discard").classList.toggle("hidden", finished);
+    $("test").disabled = busy;
+    $("apply").disabled = busy || needsAck;
+    $("discard").disabled = busy;
+    $("stepTest").classList.toggle("done", tested);
+    $("stepApply").classList.toggle("done", finished && tested);
+    reportSize();
+  }
+
+  function setStatus(kind, text) {
+    const s = $("status");
+    s.replaceChildren();
+    if (text) note(s, kind, text);
+    reportSize();
+  }
+
+  function resultPayload(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 { message: text }; }
+  }
+
+  async function act(action) {
+    if (busy || !plan) return;
+    busy = true;
+    setStatus("info", action === "test" ? t("running") : action === "apply" ? t("applying") : "");
+    updateButtons();
+    try {
+      const result = await request("tools/call", {
+        name: plan.tool,
+        arguments: { plan_id: plan.planId, code: plan.code, action, acknowledged: $("ack").checked },
+      });
+      const r = resultPayload(result);
+      const status = r.status || "";
+      if (result && result.isError || r.error) {
+        setStatus("bad", t("failed") + " " + (r.error || r.message || JSON.stringify(r)));
+        if (/no pending plan|no longer pending/i.test(String(r.error || ""))) { finished = true; setStatus("info", t("gone")); }
+      } else if (action === "test") {
+        if (status === "DRY_RUN_SUCCESS") {
+          tested = !r.dry_run_forced_by;
+          setStatus(r.dry_run_forced_by ? "warn" : "ok", r.dry_run_forced_by ? (r.remediation || t("testForced")) : (t("testOk") + (r.note ? " " + r.note : "")));
+        } else {
+          setStatus("bad", t("failed") + " " + (r.error || r.message || status));
+        }
+      } else if (action === "apply") {
+        if (status === "APPLIED" || status === "PARTIAL_UPLOAD") {
+          finished = true;
+          setStatus("ok", t("applied") + (r.message ? " " + r.message : ""));
+          tell(t("msgApplied"));
+        } else {
+          setStatus(status === "DRY_RUN_SUCCESS" ? "warn" : "bad", r.remediation || r.message || r.error || status);
+        }
+      } else if (action === "discard") {
+        finished = true;
+        setStatus("info", t("discarded"));
+        tell(t("msgDiscarded"));
+      }
+    } catch (err) {
+      setStatus("bad", t("failed") + " " + (err && err.message ? err.message : String(err)));
+    } finally {
+      busy = false;
+      updateButtons();
+    }
+  }
+
+  function tell(template) {
+    const text = template.replace("{op}", humanize(plan.preview.operation)).replace("{id}", plan.planId);
+    request("ui/message", { role: "user", content: { type: "text", text } }).catch(() => {});
+  }
+
+  function onToolResult(result) {
+    if (plan || !result) return; // later results come from the card's own calls
+    const meta = (result._meta && result._meta[META_KEY]) || null;
+    if (!meta || !meta.code || !meta.plan_id) { reportSize(); return; }
+    const preview = resultPayload(result);
+    plan = { planId: meta.plan_id, code: meta.code, tool: meta.tool || "approve_change", preview };
+    render();
+  }
+
+  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" } });
+    }
+  });
+
+  $("test").addEventListener("click", () => act("test"));
+  $("apply").addEventListener("click", () => act("apply"));
+  $("discard").addEventListener("click", () => act("discard"));
+  $("ack").addEventListener("change", updateButtons);
+  new ResizeObserver(reportSize).observe(document.documentElement);
+
+  request("ui/initialize", {
+    protocolVersion: "2026-01-26",
+    appCapabilities: { availableDisplayModes: ["inline"] },
+    clientInfo: { name: "AdLoop approval card", version: "1" },
+  }).then((result) => {
+    applyContext(result && result.hostContext);
+    notify("ui/notifications/initialized", {});
+    reportSize();
+  }).catch(() => notify("ui/notifications/initialized", {}));
+})();
+</script>
+</body>
+</html>

{adloop-0.22.2 → adloop-0.23.0}/src/adloop/server.py

@@ -8,12 +8,22 @@ import json
 from typing import Annotated, Callable
 
 from fastmcp import FastMCP
+from fastmcp.server.middleware import Middleware
 from fastmcp.utilities.docstring_parsing import parse_docstring
 from mcp.types import Icon, ToolAnnotations
 from pydantic import BeforeValidator
 
 from adloop import diagnostics
 from adloop.runtime import current_config
+from adloop.safety.approval import (
+    APPROVE_TOOL,
+    CARD_MIME_TYPE,
+    CARD_URI,
+    card_html,
+    client_shows_cards,
+    is_app_only,
+    with_card,
+)
 
 # openWorldHint: every tool talks to an external service (Google, Reddit,
 # a live web page), which directories such as ChatGPT's require to be said.
@@ -115,6 +125,11 @@ def _build_orchestration_instructions() -> str:
         "- Default to `dry_run=true` on `confirm_and_apply`. Only set "
         "`dry_run=false` after the user explicitly approves the preview. "
         "`require_dry_run` in config can override this.\n"
+        "- Approval cards: in apps that show AdLoop's approval card with a "
+        "preview (`approval: \"card\"`), the user approves with Test run and "
+        "Apply on the card. Summarize the change and let them decide there; "
+        "`confirm_and_apply` with `dry_run=false` is refused in those apps "
+        "unless the workspace allows approval in chat.\n"
         "- Respect the config's `max_daily_budget` cap.\n"
         "- New Google Ads campaigns and RSAs, and every new Reddit campaign, "
         "ad group and ad, are created PAUSED. A new Google Ads ad group is "
@@ -179,6 +194,44 @@ mcp = FastMCP(
     ],
 )
 
+
+
+@mcp.resource(
+    CARD_URI,
+    name="approval_card",
+    title="AdLoop approval card",
+    description="Renders a change preview with Test run and Apply buttons.",
+    mime_type=CARD_MIME_TYPE,
+    meta={"ui": {"prefersBorder": False}},
+)
+def approval_card() -> str:
+    return card_html()
+
+
+class _AppOnlyToolsForCardClients(Middleware):
+    """List and run app-only tools only for apps that render cards.
+
+    The MCP Apps spec makes a card-capable app hide app-only tools from its
+    model. An app without the extension knows nothing about that rule and
+    would hand them to its model, so they are not offered to it at all.
+    """
+
+    async def on_list_tools(self, context, call_next):
+        tools = await call_next(context)
+        if client_shows_cards():
+            return tools
+        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():
+            from fastmcp.exceptions import ToolError
+
+            raise ToolError(f"{APPROVE_TOOL} can only be called from the AdLoop approval card.")
+        return await call_next(context)
+
+
+mcp.add_middleware(_AppOnlyToolsForCardClients())
+
 # name -> tags of every registered tool, so health_check can say which tools
 # this server offers without reaching into FastMCP internals.
 _TOOL_TAGS: dict[str, frozenset[str]] = {}
@@ -215,6 +268,20 @@ _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})
+
+
+def _with_approval_card(fn: Callable) -> Callable:
+    """Hand a write tool's preview to the approval card when the app shows one."""
+
+    @functools.wraps(fn)
+    def wrapper(*args, **kwargs):
+        return with_card(fn(*args, **kwargs))
+
+    return wrapper
+
+
 def _tool(*, title: str, annotations: ToolAnnotations, tags: set[str], **kwargs):
     """Register a tool with its title in both places MCP defines one, and
     with a link to the API it calls.
@@ -234,13 +301,21 @@ def _tool(*, title: str, annotations: ToolAnnotations, tags: set[str], **kwargs)
         description = parse_docstring(fn).description or inspect.cleandoc(fn.__doc__ or "")
         if docs and "https://" not in description:
             description = f"{description}\n\n{docs}"
-        _TOOL_TAGS[kwargs.get("name") or fn.__name__] = frozenset(tags)
+        name = kwargs.get("name") or fn.__name__
+        options = dict(kwargs)
+        if not annotations.read_only_hint and name not in _NO_CARD_TOOLS:
+            # Write tools return a preview; apps with MCP Apps support
+            # render it as the approval card.
+            options["meta"] = {**(options.get("meta") or {}), "ui": {"resourceUri": CARD_URI}}
+            fn = _with_approval_card(fn)
+        if not is_app_only(options.get("meta")):
+            _TOOL_TAGS[name] = frozenset(tags)
         return mcp.tool(
             title=title,
             annotations=annotations,
             tags=tags,
             description=description,
-            **kwargs,
+            **options,
         )(fn)
 
     return register
@@ -3773,6 +3848,11 @@ def confirm_and_apply(
     APPLY_IN_PROGRESS means an earlier call claimed this plan first, so this
     call executed nothing.
 
+    Approval cards: in AI apps that show AdLoop's approval card with the
+    preview, dry_run=false is REFUSED with status APPROVE_ON_CARD, because
+    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.
+
     Args:
         plan_id: The plan_id returned by a prior draft_*, update_*, add_*,
             pause/enable/remove or other preview tool call. An unknown or
@@ -3781,10 +3861,78 @@ 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
 
+    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)
 
 
+@_tool(
+    title="Approve a change on its card",
+    annotations=_DESTRUCTIVE,
+    tags={"core"},
+    meta={"ui": {"resourceUri": CARD_URI, "visibility": ["app"]}},
+)
+@_safe
+def approve_change(
+    plan_id: str,
+    code: str,
+    action: str = "test",
+    acknowledged: bool = False,
+) -> dict:
+    """Run, apply or discard a previewed change from its approval card.
+
+    Called only by the AdLoop approval card when the user clicks a button;
+    AI apps keep this tool out of the model's tool list.
+
+    Args:
+        plan_id: The plan shown on the card.
+        code: The card's approval code for this plan.
+        action: "test" (dry run), "apply" (real change) or "discard".
+        acknowledged: The user ticked "cannot be undone"; required to apply a
+            plan that needs double confirmation.
+    """
+    from adloop.ads.write import confirm_and_apply as _impl
+    from adloop.safety.approval import card_click, code_matches
+    from adloop.safety.audit import log_mutation
+    from adloop.safety.preview import get_plan, remove_plan
+
+    if action not in {"test", "apply", "discard"}:
+        return {"error": "action must be test, apply or discard."}
+    plan = get_plan(plan_id)
+    if plan is None:
+        return {
+            "error": f"No pending plan '{plan_id}': it is no longer pending "
+            "(applied, discarded or expired)."
+        }
+    if not code_matches(plan, code):
+        return {"error": "This card does not match the change. Draft the change again."}
+    config = current_config()
+    if action == "discard":
+        remove_plan(plan_id)
+        log_mutation(
+            config.safety.log_file,
+            operation=plan.operation,
+            customer_id=plan.customer_id,
+            entity_type=plan.entity_type,
+            entity_id=plan.entity_id,
+            changes=plan.changes,
+            dry_run=True,
+            result="discarded",
+        )
+        return {"status": "DISCARDED", "plan_id": plan_id, "operation": plan.operation}
+    if action == "apply" and plan.requires_double_confirm and not acknowledged:
+        return {
+            "error": "This change cannot be undone: tick the confirmation on the "
+            "card before applying."
+        }
+    with card_click():
+        return _impl(config, plan_id=plan_id, dry_run=action == "test")
+
+
 # ---------------------------------------------------------------------------
 # Reddit Ads Tools
 # ---------------------------------------------------------------------------