@topy-ai/maggie 0.7.52 → 0.7.54

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.54",
   "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`;