@topy-ai/maggie 0.7.52 → 0.7.53

package/bundled-tools/clis/maggie_service_migration.py

@@ -0,0 +1,272 @@
+#!/usr/bin/env python3
+"""Dry run of moving a business's clients, future appointments and gift cards (``maggie service migrate-check``).
+
+Switching a real business from Fresha (or any system with CSV exports) needs
+more than the service catalogue: clients with consent, future appointments
+and gift-card balances. This command reads the exports and writes nothing:
+
+- recognises columns by synonyms (export headers vary by report and locale)
+  and lists anything it could not map, so the owner can fix the mapping;
+- clients: de-duplicates by e-mail, then by phone normalised to E.164 for the
+  market; keeps marketing consent only when the export says opted in;
+- appointments: keeps only future, not-cancelled rows; converts local times
+  with the **venue's** zone; matches services and staff by normalised name;
+  reports clashes (one team member, overlapping times) instead of forcing
+  them;
+- gift cards: keeps code + remaining balance (+ expiry) in their own
+  namespace (``IMPORT:<code>``) so they can never collide with new codes;
+- returns counts, a sample, row errors and the import plan with an undo key.
+
+Values (names, e-mails, phones, codes) never appear in the report: only
+counts, column names, row numbers and unmatched service/staff names.
+"""
+
+from __future__ import annotations
+
+import argparse
+import csv
+import hashlib
+import json
+import re
+import sys
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from zoneinfo import ZoneInfo
+
+SYNONYMS = {
+    "first_name": ["first name", "firstname", "given name"],
+    "last_name": ["last name", "lastname", "surname", "family name"],
+    "name": ["client", "client name", "customer", "customer name", "full name", "name"],
+    "email": ["email", "e-mail", "email address", "client email"],
+    "phone": ["mobile number", "mobile", "phone", "phone number", "telephone", "client phone"],
+    "marketing": ["marketing consent", "accepts marketing", "marketing opt-in", "email marketing", "subscribed", "marketing notifications"],
+    "notes": ["notes", "client notes", "note"],
+    "external_id": ["client id", "customer id", "id", "ref #", "reference"],
+    "date": ["appointment date", "date", "scheduled date"],
+    "time": ["start time", "time", "scheduled time"],
+    "start": ["start", "start date time", "scheduled at", "appointment start"],
+    "service": ["service", "service name", "treatment"],
+    "staff": ["team member", "staff", "staff member", "employee", "therapist"],
+    "duration": ["duration", "duration (min)", "duration minutes"],
+    "price": ["price", "amount", "total", "sale price"],
+    "status": ["status", "appointment status"],
+    "code": ["code", "voucher code", "gift card code", "card code"],
+    "balance": ["balance", "remaining balance", "remaining", "value remaining"],
+    "expiry": ["expiry", "expires", "expiry date", "expiration date"],
+}
+YES = {"yes", "y", "true", "1", "opted in", "subscribed", "accepted"}
+CANCELLED = re.compile(r"cancel|no.?show|deleted", re.I)
+COUNTRY_CODES = {"uk": "44", "us": "1"}
+
+
+def norm(value: str) -> str:
+    return re.sub(r"[^a-z0-9]+", " ", (value or "").lower()).strip()
+
+
+def map_columns(headers: list[str], wanted: list[str]) -> tuple[dict[str, str], list[str]]:
+    mapping: dict[str, str] = {}
+    for header in headers:
+        key = norm(header)
+        for field in wanted:
+            if field not in mapping and key in {norm(s) for s in SYNONYMS[field]}:
+                mapping[field] = header
+                break
+    unmapped = [h for h in headers if h not in mapping.values()]
+    return mapping, unmapped
+
+
+def e164(phone: str, market: str) -> str | None:
+    digits = re.sub(r"\D", "", phone or "")
+    if not digits:
+        return None
+    if (phone or "").strip().startswith("+"):
+        return "+" + digits
+    code = COUNTRY_CODES[market]
+    if digits.startswith("00"):
+        return "+" + digits[2:]
+    if market == "uk" and digits.startswith("0"):
+        return "+44" + digits[1:]
+    if market == "us" and len(digits) == 10:
+        return "+1" + digits
+    return "+" + (digits if digits.startswith(code) else code + digits)
+
+
+def money(value: str) -> int | None:
+    text = re.sub(r"[^\d.,-]", "", value or "").replace(",", "")
+    if not text:
+        return None
+    try:
+        return int(round(float(text) * 100))
+    except ValueError:
+        return None
+
+
+def parse_local(row: dict, mapping: dict[str, str], zone: ZoneInfo) -> datetime | None:
+    if "start" in mapping and row.get(mapping["start"]):
+        text = row[mapping["start"]].strip()
+    elif "date" in mapping and "time" in mapping:
+        text = f"{row.get(mapping['date'], '').strip()} {row.get(mapping['time'], '').strip()}"
+    else:
+        return None
+    for fmt in ("%Y-%m-%d %H:%M", "%Y-%m-%dT%H:%M", "%d/%m/%Y %H:%M", "%m/%d/%Y %H:%M", "%d %b %Y %H:%M", "%Y-%m-%d %I:%M %p", "%d/%m/%Y %I:%M %p", "%m/%d/%Y %I:%M %p"):
+        try:
+            return datetime.strptime(text, fmt).replace(tzinfo=zone)
+        except ValueError:
+            continue
+    return None
+
+
+def read_csv(path: Path) -> tuple[list[str], list[dict]]:
+    with path.open(encoding="utf-8-sig", newline="") as handle:
+        reader = csv.DictReader(handle)
+        return list(reader.fieldnames or []), list(reader)
+
+
+def migrate_check(clients: Path | None, appointments: Path | None, gift_cards: Path | None, timezone_name: str, market: str, now: datetime,
+                  services: list[str], staff: list[str], date_order: str = "auto") -> dict:
+    zone = ZoneInfo(timezone_name)
+    report: dict = {"schemaVersion": "maggie-service-migration-dry-run.v1", "writes": False, "timezone": timezone_name, "market": market}
+    errors: list[str] = []
+    warnings: list[str] = []
+    digest = hashlib.sha256()
+    if clients:
+        headers, rows = read_csv(clients)
+        digest.update(clients.read_bytes())
+        mapping, unmapped = map_columns(headers, ["first_name", "last_name", "name", "email", "phone", "marketing", "notes", "external_id"])
+        if not ({"email", "phone"} & set(mapping)):
+            errors.append("clients: no e-mail or phone column recognised; map one before importing")
+        seen_email, seen_phone, dupes, consented, kept, row_errors = set(), set(), 0, 0, 0, []
+        for index, row in enumerate(rows, start=2):
+            email = (row.get(mapping.get("email", ""), "") or "").strip().lower()
+            phone = e164(row.get(mapping.get("phone", ""), ""), market) if "phone" in mapping else None
+            if not email and not phone and not (row.get(mapping.get("name", ""), "") or row.get(mapping.get("first_name", ""), "")):
+                row_errors.append(f"row {index}: empty")
+                continue
+            if (email and email in seen_email) or (not email and phone and phone in seen_phone):
+                dupes += 1
+                continue
+            if email:
+                seen_email.add(email)
+            if phone:
+                seen_phone.add(phone)
+            kept += 1
+            if "marketing" in mapping and (row.get(mapping["marketing"], "") or "").strip().lower() in YES:
+                consented += 1
+        report["clients"] = {"rows": len(rows), "toImport": kept, "duplicatesMerged": dupes, "marketingConsent": consented, "columns": mapping, "unmappedColumns": unmapped, "rowErrors": row_errors[:20]}
+        if "marketing" not in mapping:
+            warnings.append("clients: no marketing-consent column; imported clients get no marketing (consent is never assumed)")
+    if appointments:
+        headers, rows = read_csv(appointments)
+        digest.update(appointments.read_bytes())
+        mapping, unmapped = map_columns(headers, ["start", "date", "time", "service", "staff", "duration", "price", "status", "email", "phone", "name", "external_id"])
+        if not ("start" in mapping or {"date", "time"} <= set(mapping)) or "service" not in mapping:
+            errors.append("appointments: need a start (or date + time) and a service column")
+        service_keys = {norm(name): name for name in services}
+        staff_keys = {norm(name): name for name in staff}
+        future, past, cancelled, unmatched_services, unmatched_staff, bad_rows = [], 0, 0, set(), set(), []
+        for index, row in enumerate(rows, start=2):
+            if "status" in mapping and CANCELLED.search(row.get(mapping["status"], "") or ""):
+                cancelled += 1
+                continue
+            start = parse_local(row, mapping, zone)
+            if start is None:
+                bad_rows.append(f"row {index}: unreadable date/time")
+                continue
+            if start.astimezone(timezone.utc) <= now:
+                past += 1
+                continue
+            duration = int(re.sub(r"\D", "", row.get(mapping.get("duration", ""), "") or "") or 60)
+            service = row.get(mapping["service"], "")
+            person = row.get(mapping.get("staff", ""), "") if "staff" in mapping else ""
+            if services and norm(service) not in service_keys:
+                unmatched_services.add(service)
+            if person and staff and norm(person) not in staff_keys:
+                unmatched_staff.add(person)
+            future.append({"row": index, "startUtc": start.astimezone(timezone.utc), "end": start.astimezone(timezone.utc) + timedelta(minutes=duration), "staff": norm(person)})
+        clashes = []
+        by_staff: dict[str, list[dict]] = {}
+        for item in sorted(future, key=lambda a: a["startUtc"]):
+            if not item["staff"]:
+                continue
+            for other in by_staff.get(item["staff"], []):
+                if other["end"] > item["startUtc"]:
+                    clashes.append(f"rows {other['row']} and {item['row']}: same team member at overlapping times")
+            by_staff.setdefault(item["staff"], []).append(item)
+        report["appointments"] = {"rows": len(rows), "future": len(future), "pastSkipped": past, "cancelledSkipped": cancelled, "clashes": clashes[:20], "unmatchedServices": sorted(unmatched_services)[:20],
+                                  "unmatchedStaff": sorted(unmatched_staff)[:20], "rowErrors": bad_rows[:20], "columns": mapping, "unmappedColumns": unmapped,
+                                  "firstUtc": _iso(min(a["startUtc"] for a in future)) if future else None}
+        if unmatched_services:
+            warnings.append(f"appointments: {len(unmatched_services)} service name(s) match no imported service; map them or create them first")
+        if clashes:
+            warnings.append(f"appointments: {len(clashes)} clash(es) are reported, not forced; resolve them with the business")
+    if gift_cards:
+        headers, rows = read_csv(gift_cards)
+        digest.update(gift_cards.read_bytes())
+        mapping, unmapped = map_columns(headers, ["code", "balance", "expiry"])
+        if not {"code", "balance"} <= set(mapping):
+            errors.append("gift cards: need code and balance columns")
+        codes, total, zero, bad = set(), 0, 0, []
+        for index, row in enumerate(rows, start=2):
+            code = (row.get(mapping.get("code", ""), "") or "").strip().upper()
+            balance = money(row.get(mapping.get("balance", ""), ""))
+            if not code or balance is None:
+                bad.append(f"row {index}: missing code or balance")
+                continue
+            if balance <= 0:
+                zero += 1
+                continue
+            if code in codes:
+                bad.append(f"row {index}: duplicate code")
+                continue
+            codes.add(code)
+            total += balance
+        report["giftCards"] = {"rows": len(rows), "toImport": len(codes), "zeroBalanceSkipped": zero, "totalBalanceMinor": total, "namespace": "IMPORT:<code>", "rowErrors": bad[:20], "columns": mapping, "unmappedColumns": unmapped}
+    report["undoKey"] = "import-" + digest.hexdigest()[:16]
+    report["plan"] = [
+        "create the import record (undo key) before writing",
+        "clients: insert or merge by e-mail then phone; marketing consent only when opted in",
+        "appointments: create bookings with source=import in the venue time zone; clashes stay unimported",
+        "gift cards: issue codes in the IMPORT: namespace with their balance and expiry in a paused 'Imported gift cards' voucher",
+        "undo deletes the import's bookings and the clients/team it created when unused, and voids untouched imported codes",
+        "send the optional \"we've moved\" e-mail once, only to imported clients with marketing consent, while online booking is live",
+    ]
+    report["errors"], report["warnings"] = errors, warnings
+    report["status"] = "failed" if errors else ("warning" if warnings else "ready")
+    return report
+
+
+def _iso(value: datetime) -> str:
+    return value.strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="maggie service migrate-check", description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser.add_argument("--project", type=Path, default=Path("."))
+    parser.add_argument("--clients", type=Path)
+    parser.add_argument("--appointments", type=Path)
+    parser.add_argument("--gift-cards", type=Path)
+    parser.add_argument("--timezone", required=True, help="the venue's IANA zone, e.g. Europe/London")
+    parser.add_argument("--market", choices=sorted(COUNTRY_CODES), default="uk")
+    parser.add_argument("--service", action="append", default=[], help="service name already in the catalogue (repeat)")
+    parser.add_argument("--staff", action="append", default=[], help="team member name (repeat)")
+    parser.add_argument("--now", help="ISO instant (default: now)")
+    parser.add_argument("--output", type=Path)
+    args = parser.parse_args(argv)
+    if not (args.clients or args.appointments or args.gift_cards):
+        parser.error("pass at least one of --clients, --appointments, --gift-cards")
+    now = datetime.fromisoformat(args.now.replace("Z", "+00:00")) if args.now else datetime.now(timezone.utc)
+    try:
+        report = migrate_check(args.clients, args.appointments, args.gift_cards, args.timezone, args.market, now, args.service, args.staff)
+    except (OSError, ValueError, csv.Error) as error:
+        print(f"BLOCKED: maggie service migrate-check: {error}", file=sys.stderr)
+        return 2
+    text = json.dumps(report, indent=2, ensure_ascii=False, default=str)
+    if args.output:
+        args.output.parent.mkdir(parents=True, exist_ok=True)
+        args.output.write_text(text + "\n", encoding="utf-8")
+    print(text)
+    return 1 if report["status"] == "failed" else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/bundled-tools/clis/maggie_social_queue.py

@@ -318,6 +318,8 @@ def check_campaigns(document: dict) -> dict:
             errors.append(f"campaign {cid} has invalid status {status}")
             continue
         blockers = campaign_readiness(campaign)
+        if campaign.get("plan_status") == "failed" and not campaign.get("ideas"):
+            errors.append(f"campaign {cid} was created only to be planned and the plan failed: delete it (or create it only after the plan succeeds) so retries do not pile up empty drafts")
         if status == "started" and blockers:
             errors.append(f"campaign {cid} is started but not startable: {'; '.join(blockers)}")
         report.append({"id": cid, "status": status, "can_start": not blockers, "blockers": blockers,

package/bundled-tools/clis/maggie_social_share.py

@@ -15,6 +15,18 @@ from maggie_social_queue import check_campaigns, connection_health, parse_instan
 
 LIMITS = {"linkedin": 3000, "facebook": 63206, "x": 280}
 REQUIRED = ("source_content_id", "title", "canonical_url")
+PUBLISH_MODES = ("image", "link_preview")
+LIVE_STATUSES = {"approved", "scheduled", "publishing", "published"}
+
+
+def host_of(url: str) -> str:
+    return (urlsplit(str(url or "")).hostname or "").lower().removeprefix("www.")
+
+
+def on_workspace_domain(url: str, domain: str) -> bool:
+    """True when the URL's host is the workspace domain or one of its subdomains."""
+    host, domain = host_of(url), str(domain or "").lower().strip().removeprefix("www.").rstrip(".")
+    return bool(host and domain) and (host == domain or host.endswith("." + domain))
 
 
 def read(path: Path) -> dict:
@@ -31,21 +43,31 @@ def tracked_url(url: str, channel: str) -> str:
     return urlunsplit((parsed.scheme, parsed.netloc, parsed.path, urlencode(query), parsed.fragment))
 
 
-def plan(content: dict, channels: list[str]) -> dict:
+def plan(content: dict, channels: list[str], workspace_domain: str | None = None) -> dict:
     errors = [f"missing {key}" for key in REQUIRED if not content.get(key)]
     invalid = [channel for channel in channels if channel not in LIMITS]
     if invalid:
         errors.append("unsupported channels: " + ", ".join(invalid))
+    domain = workspace_domain or content.get("workspace_domain")
+    if not domain:
+        errors.append("workspace_domain is required: posts may only share articles published on the workspace's own site")
+    elif content.get("canonical_url") and not on_workspace_domain(content["canonical_url"], domain):
+        errors.append(f"canonical_url is on {host_of(content['canonical_url'])}, not {domain}: pick an article published on this workspace's own domain")
     if errors:
         raise ValueError("; ".join(errors))
+    image = content.get("image_url")
     return {
         "schema_version": "1.0",
         "status": "draft",
         "source_content_id": content["source_content_id"],
         "title": content["title"],
         "canonical_url": content["canonical_url"],
+        "workspace_domain": domain,
         "cta": content.get("cta"),
-        "channels": [{"name": channel, "character_limit": LIMITS[channel], "tracked_url": tracked_url(content["canonical_url"], channel), "copy": None, "status": "needs-copy"} for channel in channels],
+        "image_url": image,
+        # A post with its own image goes out as an image post with the link in the text;
+        # link_preview is the default only without an image, or when the person switches it.
+        "channels": [{"name": channel, "character_limit": LIMITS[channel], "tracked_url": tracked_url(content["canonical_url"], channel), "publish_mode": "image" if image else "link_preview", "copy": None, "status": "needs-copy"} for channel in channels],
         "approval_required": True,
         "publish_requires": ["approved", "active provider connection", "explicit execute flag"],
     }
@@ -57,12 +79,30 @@ def validate(value: dict) -> list[str]:
         errors.append("invalid status")
     if value.get("status") == "published" and not value.get("provider_post_id"):
         errors.append("published draft requires provider_post_id")
+    domain = value.get("workspace_domain")
+    if domain and value.get("canonical_url") and not on_workspace_domain(value["canonical_url"], domain):
+        errors.append(f"canonical_url is on {host_of(value['canonical_url'])}, not the workspace domain {domain}")
+    elif not domain and value.get("status") in LIVE_STATUSES:
+        errors.append("workspace_domain is required before approval: the source must be published on the workspace's own domain")
     for channel in value.get("channels", []):
         name = channel.get("name")
         if name not in LIMITS:
             errors.append(f"unsupported channel: {name}")
-        if channel.get("copy") and len(channel["copy"]) > LIMITS.get(name, 0):
-            errors.append(f"copy exceeds {name} limit")
+        mode = channel.get("publish_mode")
+        if mode is not None and mode not in PUBLISH_MODES:
+            errors.append(f"{name}: publish_mode must be image or link_preview")
+        has_image = bool(channel.get("image_url") or value.get("image_url"))
+        if has_image and mode is None:
+            errors.append(f"{name}: the post has an image, so publish_mode must be set (image by default)")
+        if has_image and mode == "link_preview" and channel.get("publish_mode_source") != "user":
+            errors.append(f"{name}: an attached image would not be published as a link preview; use publish_mode image, or record publish_mode_source user when the person chose the preview")
+        if mode == "image" and not has_image:
+            errors.append(f"{name}: publish_mode image needs an image")
+        copy = channel.get("copy")
+        if copy and mode == "image" and channel.get("tracked_url") and channel["tracked_url"] not in copy and value.get("canonical_url", "") not in copy:
+            errors.append(f"{name}: an image post carries the link in its text; add the tracked URL to the copy")
+        if copy and len(copy) > LIMITS.get(name, 0):
+            errors.append(f"copy exceeds {name} limit" + (" (the link counts)" if mode == "image" else ""))
     return errors
 
 
@@ -72,6 +112,7 @@ def main() -> int:
     create = sub.add_parser("plan", help="create a draft channel contract from one content object")
     create.add_argument("input")
     create.add_argument("--channels", default="linkedin,facebook")
+    create.add_argument("--workspace-domain", help="the workspace's own site domain; the source must be published there")
     create.add_argument("--output")
     check = sub.add_parser("validate", help="validate a draft channel contract")
     check.add_argument("input")
@@ -89,11 +130,16 @@ def main() -> int:
     queue.add_argument("--from", dest="start", help="ISO 8601 instant to plan from (default: current time)")
     queue.add_argument("--slots", type=int, default=14)
     queue.add_argument("--output")
+    schema = sub.add_parser("schema-check", help="estimate a structured-output JSON schema's complexity before a model rejects it")
+    schema.add_argument("input")
     args = parser.parse_args()
     try:
         value = read(Path(args.input))
         now = datetime.now(timezone.utc)
-        if args.command == "adapters":
+        if args.command == "schema-check":
+            from maggie_schema_complexity import check_schema
+            result = check_schema(value)
+        elif args.command == "adapters":
             result = validate_adapters(value)
         elif args.command == "connections":
             result = connection_health(value, parse_instant(args.now, "--now") if args.now else now)
@@ -110,7 +156,7 @@ def main() -> int:
             return 0
         else:
             if args.command == "plan":
-                value = plan(value, [item.strip() for item in args.channels.split(",") if item.strip()])
+                value = plan(value, [item.strip() for item in args.channels.split(",") if item.strip()], args.workspace_domain)
                 if args.output:
                     Path(args.output).parent.mkdir(parents=True, exist_ok=True)
                     Path(args.output).write_text(json.dumps(value, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")

package/bundled-tools/runtime/assistant_approval.py

@@ -77,6 +77,8 @@ def verify(secret: bytes, token: str, identity: str, scope: str, calls: list[dic
     if not hmac.compare_digest(hmac.new(secret, body, hashlib.sha256).digest(), signature):
         raise ApprovalError("approval token signature does not match")
     approval = json.loads(body)
+    if approval.get("kind") == "standing":
+        raise ApprovalError("a standing approval only covers workflow runs; use check_standing")
     if approval.get("expires", 0) < (now if now is not None else time.time()):
         raise ApprovalError("approval expired; ask again")
     if not hmac.compare_digest(approval.get("principal", ""), principal_hash(identity)):
@@ -109,3 +111,99 @@ class TurnStore:
         if not token:
             raise ApprovalError("no pending approval for this turn (already used or never proposed)")
         return token
+
+
+# --- Standing approvals -------------------------------------------------------
+#
+# Scheduled and event-driven workflows ("when someone cancels, offer the slot to
+# the waitlist") cannot ask for a card every time. A standing approval is a
+# signed grant bound to one workflow, its tools, per-tool limits and an expiry.
+# Every run inside the limits is audited with channel "workflow" and the grant
+# id; a call outside the limits raises OutsideStandingApproval and the caller
+# falls back to a normal approval card. Revocation and daily usage live on the
+# server (StandingStore models them).
+
+MAX_STANDING_DAYS = 90
+
+
+class OutsideStandingApproval(ApprovalError):
+    """The call is not covered by the grant: ask with a normal approval card."""
+
+
+def issue_standing(secret: bytes, identity: str, scope: str, workflow: str, grants: list[dict], days: int = 30, now: float | None = None) -> tuple[str, dict]:
+    if not workflow or not grants:
+        raise ApprovalError("a standing approval needs a workflow and at least one tool grant")
+    if not 1 <= days <= MAX_STANDING_DAYS:
+        raise ApprovalError(f"a standing approval lasts 1-{MAX_STANDING_DAYS} days; renew it instead of making it permanent")
+    for grant in grants:
+        if not grant.get("name") or not isinstance(grant.get("maxPerDay"), int) or grant["maxPerDay"] < 1:
+            raise ApprovalError("every tool grant needs a name and maxPerDay")
+    approval = {
+        "kind": "standing",
+        "id": secrets.token_hex(16),
+        "workflow": workflow,
+        "grants": [{key: grant[key] for key in ("name", "maxPerDay", "maxPerRun", "fixedArgs", "maxAmountMinor") if key in grant} for grant in grants],
+        "principal": principal_hash(identity),
+        "scope": scope,
+        "expires": int((now if now is not None else time.time()) + days * 86400),
+    }
+    body = canonical(approval).encode("utf-8")
+    return _b64(body) + "." + _b64(hmac.new(secret, body, hashlib.sha256).digest()), approval
+
+
+def _decode(secret: bytes, token: str) -> dict:
+    try:
+        body_text, signature_text = token.split(".", 1)
+        body, signature = _unb64(body_text), _unb64(signature_text)
+    except (ValueError, TypeError) as error:
+        raise ApprovalError("approval token is malformed") from error
+    if not hmac.compare_digest(hmac.new(secret, body, hashlib.sha256).digest(), signature):
+        raise ApprovalError("approval token signature does not match")
+    return json.loads(body)
+
+
+def check_standing(secret: bytes, token: str, identity: str, scope: str, workflow: str, call: dict, used_today: int, run_calls: int = 0, revoked: set[str] | None = None, now: float | None = None) -> dict:
+    """Allow one workflow call under a standing approval, or raise (OutsideStandingApproval = ask with a card)."""
+    approval = _decode(secret, token)
+    if approval.get("kind") != "standing":
+        raise ApprovalError("not a standing approval")
+    if approval["id"] in (revoked or set()):
+        raise OutsideStandingApproval("this standing approval was revoked; ask again")
+    if approval.get("expires", 0) < (now if now is not None else time.time()):
+        raise OutsideStandingApproval("this standing approval expired; ask the owner to renew it")
+    if not hmac.compare_digest(approval.get("principal", ""), principal_hash(identity)) or approval.get("scope") != scope:
+        raise ApprovalError("standing approval belongs to another owner or workspace")
+    if approval.get("workflow") != workflow:
+        raise OutsideStandingApproval("the standing approval covers another workflow")
+    grant = next((g for g in approval.get("grants", []) if g.get("name") == call.get("name")), None)
+    if grant is None:
+        raise OutsideStandingApproval(f"{call.get('name')} is not part of this workflow's standing approval")
+    if used_today >= grant["maxPerDay"]:
+        raise OutsideStandingApproval(f"daily limit of {grant['maxPerDay']} reached for {call['name']}")
+    if grant.get("maxPerRun") and run_calls >= grant["maxPerRun"]:
+        raise OutsideStandingApproval(f"limit of {grant['maxPerRun']} per run reached for {call['name']}")
+    args = call.get("args", {})
+    for key, value in (grant.get("fixedArgs") or {}).items():
+        if args.get(key) != value:
+            raise OutsideStandingApproval(f"{call['name']}: {key} differs from the approved value")
+    if grant.get("maxAmountMinor") is not None and int(args.get("amountMinor", 0)) > grant["maxAmountMinor"]:
+        raise OutsideStandingApproval(f"{call['name']}: amount above the approved maximum")
+    return {"approvalId": approval["id"], "workflow": workflow, "auditChannel": "workflow", "idempotencyKey": idempotency_key(approval["id"], call)}
+
+
+class StandingStore:
+    """Server-side model: revocations and per-day usage per grant and tool."""
+
+    def __init__(self) -> None:
+        self.revoked: set[str] = set()
+        self.usage: dict[tuple[str, str, str], int] = {}
+
+    def revoke(self, approval_id: str) -> None:
+        self.revoked.add(approval_id)
+
+    def run(self, secret: bytes, token: str, identity: str, scope: str, workflow: str, call: dict, day: str, run_calls: int = 0, now: float | None = None) -> dict:
+        approval_id = _decode(secret, token).get("id", "")
+        key = (approval_id, call.get("name", ""), day)
+        allowed = check_standing(secret, token, identity, scope, workflow, call, self.usage.get(key, 0), run_calls, self.revoked, now)
+        self.usage[key] = self.usage.get(key, 0) + 1
+        return allowed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topy-ai/maggie",
-  "version": "0.7.52",
+  "version": "0.7.53",
   "description": "Install and manage Maggie Skills for AI coding agents",
   "license": "MIT",
   "type": "module",

package/references/provider-adapter-contract.md

@@ -173,9 +173,22 @@ rules from a redacted JSON manifest; see the Social Share skill for shapes.
 
 ## Structured model output
 
-Keep structured-output schemas small. Gemini rejected a JSON schema whose enum
-had 125 values with `400 INVALID_ARGUMENT`, and the caller silently fell back
-for every request. For a large vocabulary (styles, categories, catalogue IDs):
+Keep structured-output schemas small. The limit is **schema complexity**, not
+vocabulary size: roughly enum values × repeated array items × nesting.
+Gemini rejected a JSON schema whose enum had 125 values with
+`400 INVALID_ARGUMENT`, and the caller silently fell back for every request.
+It also rejected a plan schema with a 5-6 value `template_key` enum on each
+of up to 20 array items (`maxItems: 20`) — immediately and with no detail —
+while 4 values or `maxItems: 10` passed. So:
+
+- never put an `enum` inside repeated array items; describe the allowed
+  values in the prompt or the field `description` and validate server-side;
+- keep `maxItems` small on arrays of objects, and always set it;
+- run `maggie tool maggie_social_share.py schema-check schema.json`
+  (`tools/clis/maggie_schema_complexity.py`) before a release; it fails on
+  the patterns above and reports an estimated complexity score.
+
+For a large vocabulary (styles, categories, catalogue IDs):
 
 1. ask for a free string (optionally with a short list of examples in the
    prompt) instead of a large `enum`;