{"ok":true,"tool":"swarm-rate-gate","module_version":"0.1.0","result":{"slug":"swarm-rate-gate","name":"Swarm Rate Gate","version":"0.1.0","category":"coordination","status":"beta","mode":"atomic","summary":"Share a bounded, retry-safe token budget across an agent swarm.","description":"Atomically consumes tokens from an opaque distributed bucket. The first consume locks capacity, refill cadence, and expiry; mismatched configurations and altered operation-key retries never consume tokens.","when_to_use":["Several agents share one provider, API, or model token budget.","A distributed token bucket must make retry-safe decisions without exposing raw resource identifiers."],"do_not_use_when":["The provider itself already enforces the only required quota.","A durable billing ledger or account-level subscription is required."],"tested_with":["Valkey 8","parallel consumers","HTTP/1.1","MCP Streamable HTTP"],"input_schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","oneOf":[{"type":"object","properties":{"namespace":{"type":"string","minLength":1,"maxLength":80,"pattern":"^[a-zA-Z0-9._:-]+$"},"key":{"type":"string","minLength":1,"maxLength":256},"capacity":{"type":"integer","minimum":1,"maximum":1000},"refill_tokens":{"type":"integer","minimum":1,"maximum":1000},"refill_interval_seconds":{"type":"integer","minimum":1,"maximum":3600},"ttl_seconds":{"type":"integer","minimum":5,"maximum":3600},"operation_key":{"type":"string","minLength":1,"maxLength":128},"requested_tokens":{"type":"integer","minimum":1,"maximum":1000},"action":{"type":"string","const":"consume"}},"required":["namespace","key","capacity","refill_tokens","refill_interval_seconds","ttl_seconds","operation_key","requested_tokens","action"],"additionalProperties":false},{"type":"object","properties":{"namespace":{"type":"string","minLength":1,"maxLength":80,"pattern":"^[a-zA-Z0-9._:-]+$"},"key":{"type":"string","minLength":1,"maxLength":256},"capacity":{"type":"integer","minimum":1,"maximum":1000},"refill_tokens":{"type":"integer","minimum":1,"maximum":1000},"refill_interval_seconds":{"type":"integer","minimum":1,"maximum":3600},"ttl_seconds":{"type":"integer","minimum":5,"maximum":3600},"action":{"type":"string","const":"status"}},"required":["namespace","key","capacity","refill_tokens","refill_interval_seconds","ttl_seconds","action"],"additionalProperties":false}]},"output_schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"action":{"type":"string","enum":["consume","status"]},"gate_hash":{"type":"string"},"exists":{"type":"boolean"},"configuration_matches":{"type":"boolean"},"operation_matches":{"type":"boolean"},"operation_replayed":{"type":"boolean"},"decision":{"type":"string","enum":["allowed","denied","status"]},"denial_reason":{"anyOf":[{"type":"string","enum":["insufficient_tokens","configuration_mismatch","idempotency_conflict","idempotency_capacity_reached"]},{"type":"null"}]},"requested_tokens":{"anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},{"type":"null"}]},"remaining_tokens":{"type":"integer","minimum":0,"maximum":9007199254740991},"retry_after_ms":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"capacity":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"refill_tokens":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"refill_interval_seconds":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"expires_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},{"type":"null"}]}},"required":["action","gate_hash","exists","configuration_matches","operation_matches","operation_replayed","decision","denial_reason","requested_tokens","remaining_tokens","retry_after_ms","capacity","refill_tokens","refill_interval_seconds","expires_at"],"additionalProperties":false},"payment":{"kind":"free"},"side_effects":["Consume creates a fixed-lifetime gate on first use.","An allowed unique operation atomically consumes requested tokens."],"retention":"Only hashes of the namespace, key, and successful operation keys remain in Valkey until the gate's fixed expiry. Raw identifiers are never returned or stored; successful-operation deduplication is capped.","limits":{"max_capacity":1000,"max_refill_tokens":1000,"max_refill_interval_seconds":3600,"max_ttl_seconds":3600,"max_operation_keys":10000,"max_key_bytes":256,"max_client_requests_per_minute":30,"max_global_requests_per_minute":120},"examples":{"input":{"action":"consume","namespace":"provider:example.invalid","key":"shared-api-budget","capacity":10,"refill_tokens":2,"refill_interval_seconds":30,"ttl_seconds":600,"operation_key":"crawl-batch-42","requested_tokens":3},"output":{"action":"consume","gate_hash":"sha256:eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee","exists":true,"configuration_matches":true,"operation_matches":true,"operation_replayed":false,"decision":"allowed","denial_reason":null,"requested_tokens":3,"remaining_tokens":7,"retry_after_ms":null,"capacity":10,"refill_tokens":2,"refill_interval_seconds":30,"expires_at":"2026-07-24T12:10:00.000Z"},"negative":[{"scenario":"The provider itself already enforces the only required quota.","expected_error":"INVALID_INPUT","charged":false}]},"execution":{"errors":[{"code":"INVALID_INPUT","retryable":false,"charged":false,"recovery":"Correct the request to match input_schema."},{"code":"TOOL_PAUSED","retryable":true,"charged":false,"recovery":"Wait for the operator to resume the tool."},{"code":"RATE_LIMITED","retryable":true,"charged":false,"recovery":"Retry after the response Retry-After interval."},{"code":"DEPENDENCY_UNAVAILABLE","retryable":true,"charged":false,"recovery":"Retry with the same idempotency identity."}],"idempotency":{"required":true,"mock_or_unpaid_header":"Idempotency-Key","x402_extension":null,"replay_retention":"up to 24 hours"}},"endpoints":{"describe":"/v1/tools/swarm-rate-gate","execute":"/v1/tools/swarm-rate-gate"}},"meta":{"request_id":"req_becadd2952614e06a2afc54e60f285fe","observed_at":"2026-07-25T07:18:06.204Z"}}